Self-Hosted: Updating your Hudu Version

To update your Hudu instance on self-hosted:

Before updating, always make sure you have a current backup. Plan for about 5-10 minutes of downtime.

To update your Hudu instance to a new version, run:

cd ~/hudu2 && sudo docker compose down && sudo docker compose pull && sudo docker compose up -d

If you are using an older version of Docker, run:

cd ~/hudu2 && sudo docker-compose down && sudo docker-compose pull && sudo docker-compose up -d

Redis Update

Hudu requires Redis 6 or higher. We recommend Redis 7.2.4-alpine or later. The Redis version is set in the docker-compose.yml file in your ~/hudu2 directory. To ensure you stay on the latest version, replace the Redis image tag with latest.

Additional default.conf Updates by Version

v2.35.0 through v2.41.x

If you are updating your self-hosted instance to v2.35.0 or any version up to v2.41.x, add the required /cable location block beneath the final deny block in default.conf.

Navigate to /var/www/hudu2/config/nginx/site-confs/ and edit default.conf to include the following block under the last deny block:

location /cable {
    proxy_pass http://app:3000/cable;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 240s;
    proxy_send_timeout 240s;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass_request_headers on;
    proxy_buffering off;
    proxy_redirect off;
    break;
}

v2.42.0 and later

If you are updating your self-hosted instance to v2.42.0 or later, you must also add the following three location blocks above all previously configured locations.

If the /cable block is not already present, it must also be added:

location = /.well-known/oauth-authorization-server {
    limit_except GET { deny all; }

    client_max_body_size 1k;

    # add_header Content-Type application/json;

    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_pass http://app:3000;
}

location = /.well-known/oauth-protected-resource {
    limit_except GET { deny all; }

    client_max_body_size 1k;

    # add_header Content-Type application/json;

    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_pass http://app:3000;
}

location /mcp {
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;

    proxy_buffering off;
    proxy_cache off;

    proxy_http_version 1.1;
    proxy_set_header Connection "";

    chunked_transfer_encoding off;
    gzip off;

    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_pass http://app:3000;
}

You can find the fully updated default.conf file in our setup guides. Each setup guide has slight variations for its default.conf file, so make sure you use the one from the guide you used to set up your instance:

• Standard Setup Guide for Self-Hosted
• Self-Hosting with Custom SSL Cert
• Self-Hosting with No SSL Certificate

Docker Cleanup

Over time, your Hudu server may accumulate old Docker images and stopped containers that take up unnecessary disk space. Running a prune command during the update process helps keep your environment clean and efficient.

sudo docker system prune -af

What This Does

• Removes unused Docker images, containers, and networks.
• Frees up space by clearing cached data from previous builds.
• Keeps your Hudu data and volumes intact.

Recommended Routine

When updating Hudu, run the following commands:

cd ~/hudu2
sudo docker compose down
sudo docker system prune -af
sudo docker compose pull
sudo docker compose up -d

This ensures your Hudu installation runs on a clean and current Docker environment, minimizing conflicts and improving performance.

When to Run This

It's recommended to run this cleanup process:

• As part of your regular Hudu update routine.
• Monthly, as part of ongoing server maintenance.
• Whenever Docker begins consuming significant storage space.

Redis Cleanup

How do I remove unused Redis volumes left behind by older installs?

After updating Redis, run the following to remove Docker volumes that are no longer attached to any container:

sudo docker volume prune

On Docker Engine 23 and later, this removes only unnamed volumes, so named volumes such as your database and uploads are not affected.

How do I clear Redis if background jobs appear stuck?

Redis data persists across restarts and updates, so pending or stuck background jobs do as well. To clear the cache and all job queues without affecting anything else, run the following from the ~/hudu2 directory:

sudo docker compose exec redis redis-cli FLUSHALL

Recurring jobs re-register automatically. Any one-off jobs that were still pending are removed.

How do I fully reset Redis?

To remove the Redis volume entirely and start with a fresh one, run the following from the ~/hudu2 directory:

sudo docker compose down
sudo docker volume rm hudu2_redis_data
sudo docker compose up -d