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
hudu2on 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. The contents can be found here.
- 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 -dto 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 downto 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: here.
- 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. Reach out to support for a license key.
- If you don't see this screen, contact support, and please provide logs:
sudo docker compose logs
-
- Please paste these into something like Pastebin.com
Having Issues?
- Have you checked that your ports are open? Use this tool.
- Are you pasting in the .env or docker-compose.yml from a Windows computer? It could be formatted incorrectly.
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 -dto take it down and back up again. - After a few minutes, it should work by browsing to the URL.
- You will then