Standard Setup Guide for Self-Hosted

This guide is for setting up Hudu with a free LetsEncrypt SSL certificate that will renew automatically for you. If you are looking to use a custom SSL certificate, you may want to read this article for alternative options: Getting Started with Hudu Self-Hosted.

    This standard, LetsEncrypt method, is Hudu's recommended setup method for self-hosting.

 

Prerequisites

In order to self-host Hudu, you will need:

  • Server with at least 4GB memory and at least 1 CPU (as long as there is no contention), with Ubuntu (18.04, 20.04, or 22.04) as the OS.
  • SMTP server for sending outgoing mail.
  • An A record pointed to the Public IP of the instance. Usually something like docs.mywebsite.com or hudu.mywebsite.com
  • Ports 443 and 80 opened externally (required for LetsEncrypt).

 

Guides

Video Instructions

Would you prefer a video walk-through of the setup? Here is a video from one of our great partners.

   Please note! In the video, he utilizes DigitalOcean for the setup; if you'd like to use a different hosted managed service provider, you may need to modify some steps.

 

Instructions

  • 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
  • Place a file named docker-compose.yml in the directory.
    Expand to copy the content for the docker-compose.yml file
    volumes: 
      postgres_data: {}
      app_data: {}
      redis_data: {}
    services:
      db: 
        image: 'postgres:16.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:7.2.4-alpine'
        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

        Already have a production environment and want to update your docker-compose.yml file? Please visit our Upgrade Postgres in a Production Environment article for more information!

  • Place a file named .env in the directory. The contents need to be generated with our config generator: here.

    It is critical that you store an exact copy of the .env file in a secure location. Your encryption and secure keys are located in this file, and you can lose access to passwords and more if this file is lost.

  • When both files are residing within the directory, run the command: sudo docker compose up -d to start your Hudu instance.
  • 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 defaulthere.
  • 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.

create account.png

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

 

Reaching "SWAG" page / can't reach login page

Answer: This typically means that the default NGINX file didn't get replaced, or you didn't restart the server after changing it out with cd ~/hudu2 && sudo docker-compose down && sudo docker-compose up -d

Notes: If this DOES NOT resolve the issue:

  • Delete the default.conf file and use the mv command (mv default default.conf) to move the contents of the default file to the default.conf file.
  • You should end up with the defaulf.conf and default.conf.sample files in that folder.
    • You will then cd ~/hudu2 && sudo docker-compose down && docker-compose up -d to take it down and back up again.
    • After a few minutes, it should work by browsing to the URL.
Was this article helpful?
2 out of 2 found this helpful