Standard Setup Guide for Self-Hosted

• Test that ports 443 and 80 are opened for your publicly accessible A record.
  • Enter your URL to this tool. If both ports aren't showing as open, then you will need to fix that first.
• SSH into the server you are wishing to host Hudu on.
• Install Docker CE on the server. Setup instructions can be found here. Do not use SNAP to install Docker - this will cause issues later on.
• Create a blank directory named hudu2 on the home directory. On Ubuntu, you can do this by typing:

  mkdir ~/hudu2

• Move into the directory. On Ubuntu:

cd ~/hudu2

volumes: 
  postgres_data: {}
  app_data: {}
  redis_data: {}
services:
  db: 
    image: 'postgres:17.2'
    volumes: 
      - postgres_data:/var/lib/postgresql/data
    env_file:
      - '.env'
    logging:
      driver: "json-file"
      options:
        max-file: "5"
        max-size: "10m"
    restart: unless-stopped
  redis:
    image: 'redis:latest'
    command: redis-server
    volumes:
      - redis_data:/var/lib/redis/data
    restart: unless-stopped
  app: 
    image: hududocker/hudu:latest
    env_file:
      - '.env'
    volumes:
      - app_data:/var/www/hudu2/public/uploads/
      - app_data:/var/www/hudu2/uploads/ 
      - app_data:/var/lib/app/data
    depends_on: 
      - db
      - redis
    logging:
      driver: "json-file"
      options:
        max-file: "5"
        max-size: "100m"
    restart: unless-stopped
  worker:
    depends_on:
      - db
      - redis
    image: hududocker/hudu:latest
    command: bundle exec sidekiq -C config/sidekiq.yml
    volumes:
      - app_data:/var/www/hudu2/public/uploads/
      - app_data:/var/www/hudu2/uploads/
      - '.:/app'
    env_file:
      - '.env'
    logging:
      driver: "json-file"
      options:
        max-file: "5"
        max-size: "100m"
    restart: unless-stopped
  letsencrypt:
    image: lscr.io/linuxserver/swag
    container_name: letsencrypt
    cap_add:
      - NET_ADMIN
    env_file:
      - '.env'
    depends_on:
      - app
    volumes:
      - /var/www/hudu2/config:/config
    ports:
      - 443:443
      - 80:80
    restart: unless-stopped

cd ~/hudu2 && bash <(curl -fsSL https://raw.githubusercontent.com/Hudu-Technologies-Inc/self-hosting/refs/heads/main/hudu-env-wizard.sh)

• When both files are residing within the directory, run this command to start your Hudu instance:

  sudo docker compose up -d

• Wait for the command to execute. You will know it is done when you can visit your domain and see a page referring to SWAG (the name of the SSL Cert Tool we use).
• You will now need to set up an SSL certificate for your instance. Type

  sudo docker compose down

  to shut down your instance.
• Navigate to /var/www/hudu2/config/nginx/site-confs/. With Ubuntu, you can do this by typing:

  cd /var/www/hudu2/config/nginx/site-confs/

• Edit the file named default.conf and replace ALL of the contents with this file named default:
  Expand to copy the content for the default.conf file

  ## Version 5/14/2026 - Changelog: https://github.com/linuxserver/docker-letsencrypt/commits/master/root/defaults/default
  
  # redirect all traffic to https
  server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    return 301 https://$host$request_uri;
  }
  
  server { 
   server_name _;
   
   listen 443 ssl; 
   listen [::]:443 ssl; 
   http2 on;
    
    root   /var/www/hudu2/public;
    index  index.html;
  
    include /config/nginx/ssl.conf;
  
    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_set_header Connection '';     
          proxy_http_version 1.1;
  	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;
      }
  
    # deny requests for files that should never be accessed
    location ~ /\. {
      deny all;
    }
  
    location ~* ^.+\.(rb|log)$ {
      deny all;
    }
    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;    
    }
  
    # send non-static file requests to the app server
    location / {
      try_files $uri @rails;
    }
  
    location @rails {
      include /config/nginx/proxy.conf;
      proxy_pass http://app:3000;
    }
  }
  
  # enable subdomain method reverse proxy confs
  include /config/nginx/proxy-confs/*.subdomain.conf;
  # enable proxy cache for auth
  proxy_cache_path cache/ keys_zone=auth_cache:10m;

• Navigate back to the hudu2 folder. On Ubuntu:

  cd ~/hudu2

• Start the instance again:

  sudo docker compose up -d

• Your Hudu should now be up and running! Visit your domain to confirm. If you see a Hudu sign-up screen, it's successful. Head to the Hudu HQ Billing Portal for a license key.

• If you don't see this screen, contact support, and please provide logs:

  sudo docker compose logs