Getting Started With Hudu Self-Hosted

Looking to get started with the Hudu Self-Hosted solution? You've come to the right place. Depending on your criteria and your desired goals, we have different guides you may want to use.


Setup Methods


Which guide should I use?

    Hudu's recommended setup method would be the Standard Guide using LetsEncrypt!



Best For  Downsides of Guide
Standard Setup Guide for Self-Hosted Most users. This setup bundles Hudu with a free LetsEncrypt SSL certificate that auto-renews. You will need to keep ports 443 and 80 open from the outside.
Custom SSL Certificate Guide Users who want to use their own SSL certificate, or users who want to keep everything internal (no outside access) in a secure manner Requires a custom SSL Certificate.
No SSL Certificate Guide Users who want to keep their Hudu instance internal (no outside access) This approach is not recommended for security reasons unless you are fully locking down your environment.



What are my options for self-hosting?

Answer: We recommend that you self-host Hudu on a cloud provider such as DigitalOcean or Amazon Web Services, but you may also host Hudu on-premise.

Our recommended approach to host Hudu on a cloud provider like DigitalOcean or Amazon Web Services is because these environments are similar to how we host Magic Cloud Instances. This means we have more knowledge of troubleshooting when issues arise.

Ultimately, this is your decision, and know that many have hosted internally without any issues.

Can I self-host using alternate methods?

Answer: The self-hosted infrastructure is fully dockerized, meaning that it is very transportable and could likely be hosted using numerous strategies. With this being said, we can only support our recommended setup methods.

If you choose to self-host using an alternative method and are successful, please reach out! We'd love to see and chat about it so that we can expand our support capabilities.

What are the advantages of self-hosting?

Answer: The advantages of self-hosting are numerous. Self-hosting creates possibilities that are non-existent in distribution methods.

    • One significant benefit is the ability to control your documentation, without having to trust another party with sensitive information.
    • Another benefit is the ability to control downtime, so your business processes are not at risk when another party is having technical issues.
Is it the same feature set as Hosted?

Answer: Yes, both Hudu Self-Hosted and our Hosted versions have the same feature capabilities.

How long will setup take?

Answer: Usually, expect to allocate 30 minutes for setup.

This will depend on your level of technical knowledge when it comes to networking, Docker, and server setup.

How long will maintenance take?

Answer: Expect maintenance to take ~20 minutes.

Your Hudu instance will be down during this time, so make sure to do it at times when no one is accessing the service. Also, always make sure to validate that you have a current backup before updating.

What data is sent to Hudu?

Answer: For licensing purposes, ONLY the following information is sent from your self-hosted environment to our servers:

    • # of active users

NO other data is sent to our servers.



Common mistakes when setting up


    • Missing .env information. You will need to fill out all the required information.
    • Not putting https:// at the beginning of the S3_ENDPOINT. Your Docker will not start if this is missing. Make sure it is https:// NOT http://. Hudu does not allow unencrypted images to be displayed, and you will see broken links.
How can I test whether my ports are forwarded/security rules are correct?

Answer: If you have Python on the machine, a simple way is to throw up a server on port 80:

    • Typepython -v
    • If the Python version returned is 3.X, then typesudo python3 -m http.server 80
    • If it is 2.X, then typesudo python -m SimpleHTTPServer 80
    • If you visit your IP address on port 80, you should be seeing a directory listing. If not, something is wrong with your port forwarding or security rules.
I need help, what should I send to Hudu Support?

Answer: To help Hudu Support, please send us the output of sudo docker compose logs. That is usually the quickest way to see what is going wrong with your instance. Please also include additional context in terms of where you are in the setup process.

You can use a service like to send us the info.

If you send us .env info, please make sure that all confidential information is taken out before sending.
For additional information on retrieving this information, see the question below.

How do I retrieve the information to send to support for help?

Answer: To grab the information needed to assist with self-hosting issues:

  • SSH into the server either using a product such as PuTTY (Windows) or Mac Terminal
  • Login to your server as root user or a user with sudo capability
  • You'll then need to find the hudu2 folder. 
    • Typically this is done by typing cd ~/hudu2 (however, you might need to use the find command to location the folder, ie. find / -name docker-compose.yml -print
  • To retrieve the files:
    • Docker-compose.yml file, type: more docker-compose.yml
    • ENV file, type: more .env 
      • Please obfuscate/remove any passwords or sensitive information; all of the variables with KEY
    • Copy these files and paste into a text editor product.
  • To retrieve the logs:
    • Type sudo docker compose logs > hudu.log
    • If you receive an error when running the above command, this means you are using and older version of Docker. For older version of Docker, use: sudo docker-compose logs > hudu.log
  • Transfer the log files either using WinSCP (Windows) or SCP (Mac)
Was this article helpful?
1 out of 1 found this helpful