{"id":26495136,"url":"https://github.com/edythecow/docker-whmcs","last_synced_at":"2025-10-24T03:14:23.494Z","repository":{"id":103520220,"uuid":"388119739","full_name":"EdyTheCow/docker-whmcs","owner":"EdyTheCow","description":"Dockrized WHMCS running under Traefik proxy! Fully functional and ready for production use.","archived":false,"fork":false,"pushed_at":"2024-07-31T19:10:23.000Z","size":99,"stargazers_count":29,"open_issues_count":2,"forks_count":10,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-07-31T23:18:35.876Z","etag":null,"topics":["docker","docker-compose","traefik","whmcs"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EdyTheCow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-21T13:06:53.000Z","updated_at":"2024-07-31T19:10:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"08e23702-5de1-45f1-9496-b04963344baa","html_url":"https://github.com/EdyTheCow/docker-whmcs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdyTheCow%2Fdocker-whmcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdyTheCow%2Fdocker-whmcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdyTheCow%2Fdocker-whmcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdyTheCow%2Fdocker-whmcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EdyTheCow","download_url":"https://codeload.github.com/EdyTheCow/docker-whmcs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244597983,"owners_count":20479029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","traefik","whmcs"],"created_at":"2025-03-20T10:36:18.488Z","updated_at":"2025-10-24T03:14:23.475Z","avatar_url":"https://github.com/EdyTheCow.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"400\" src=\"https://raw.githubusercontent.com/BeefBytes/Assets/master/Other/container_illustration/v2/dockerized_whmcs.png\"\u003e\n\u003c/p\u003e\n\n# 📚 About\nThe point of this project is a production ready solution for running WHMCS in docker under Traefik reverse proxy. There's already a couple other projects attempting something similar. However, they are either meant for development only, are outdated and/or not optimized to be ran under Traefik. This project complies with all of the official WHMCS security and packages recommendations that are found at [\"Further Security Steps\"](https://docs.whmcs.com/Further_Security_Steps) and [\"System Environment Guide\"](https://docs.whmcs.com/System_Environment_Guide).\n\n\u003e [!NOTE]  \n\u003e This exact installation is currently being used in live production. It is being actively maintained and tested. PRs, suggestions and issue reports are more than welcome. Consider leaving a star if you found this project helpful! ❤️\n\n# ✨ Features\n- **Pre-built docker images**: whmcs-nginx and whmcs-php-fpm, ready to be deployed\n- **As minimal as possible**, includes only configuration and dependencies needed to run WHMCS\n- **Based on official images**: nginx and php-fpm, no weird and obscure base image\n- **Follows best practices** according to official WHMCS docs (references are provided below)\n- **Uses WHMCS public API** to download WHMCS files into docker volume automatically\n- **Modular scripts to automate** parts of installation and configuration (more info in docker-images branch)\n- **Dokploy support**, easily deploy WHMCS using provided docker compose in `whmcs-dokploy`\n\n# 👓 Quick Overview\nThe `_base` directory currently only includes Traefik. If you're already using Traefik, you can use it as a guide and plug \u0026 play the `whmcs` part into your existing setup. Directory `whmcs-dokploy` can be ignored. If you're interested in using Dokploy, read the instructions found inside of `whmcs-dokploy`.\n\nBoth `_base` and `whmcs` has directories called `compose` (stores compose file and .env) and `data` (stores all of data generated by compose). This is just a structure I came up with that I use for all my projects.\n\nTo simplify installation further, pre-built docker images with dependencies and configuration are used for this setup. These images can be inspected in the `docker-images` branch.\n\n# 🧰 Getting Started\nThis project uses Nginx instead of Apache as a web server, WHMCS was developed with Apache in mind so few extra steps are required to achieve production ready setup. Majority of modifications have been already implemented, rest of manual modifications are covered in the guide below.\n\n## Requirements\n- Domain\n- Valid WHMCS license\n\n# 🏗️ Installation\n\u003cb\u003eClone repository\u003c/b\u003e\n```\ngit clone https://github.com/EdyTheCow/docker-whmcs.git\n```\n\n\u003cb\u003eSet correct acme.json permissions\u003c/b\u003e\u003cbr /\u003e\nNavigate to `_base/data/traefik/` and run:\n```\nsudo chmod 600 acme.json\n```\n\n\u003cb\u003eCreate docker network\u003c/b\u003e\u003cbr /\u003e\n```\ndocker network create docker-whmcs-network\n```\n\n\u003cb\u003eGenerate basic auth user and password\u003c/b\u003e\u003cbr /\u003e\nThis will set a basic auth for WHMCS admin page. Setting this up is highly recommended. In practice this means, as an admin you'll have to login with basic auth and then login with WHMCS admin credentials. This is extremely effective against bots and endless spam of attempted and failed logins. Basic auth is usually cached by web browser, normally you'll only need to login once. This will not affect normal users, only admins.\n\nDon't use the same credentials as WHMCS admin account in case you'll have to share it with another admin. You can set up multiple basic auth credentials, but this is only used as a simple tactic against bots, so set it as something simple. You'll still need WHMCS admin credentials to actually login into WHMCS. If you don't want this, simply remove traefik labels under comment \"Basic auth for /admin page\" in `docker-compose.yml`.\n\nTo generate basic auth credentials you can use this one-liner command. It uses the official Apache docker image from official source on Docker Hub.\n```\ndocker run --rm --entrypoint htpasswd httpd:latest -Bbn YOUR_USER_HERE YOUR_PASSWORD_HERE | sed -e s/\\\\$/\\\\$\\\\$/g\n```\nPaste the output into `whmcs/compose/.env` for variable `BASIC_AUTH_CREDENTIALS`.\n\n\u003cb\u003eStart docker compose\u003c/b\u003e\u003cbr /\u003e\nInside of `_base/compose/` run the command below. This will start Traefik reverse proxy.\n ```\ndocker-compose up -d\n ```\n\n\u003cb\u003eSet .env variables for WHMCS\u003c/b\u003e\u003cbr /\u003e\nNavigate to `whmcs/compose/.env` and set these variables:\n| Variable            | Example             | Description                                      |\n|---------------------|---------------------|--------------------------------------------------|\n| DOMAIN              | portal.domain.com   | Domain for WHMCS installtation                   |\n| MYSQL_PASSWORD      | MySQL user password | Generate a password for your mysql user          |\n| MYSQL_ROOT_PASSWORD | MySQL root password | Do not use the same password, generate a new one |\n| TRAEFIK_SUBNET      | 172.18.0.0/16       |  It's normally 172.18.x.x you can find it by running docker inspect on the traefik container and looking for `docker-whmcs-network` |\n| PUBLIC_SERVER_IP    | -                   | This is used to verify the WHMCS license. Insert your server's public / external IP |\n\nIf you're still unsure about your Traefik's subnet, set it as example value shown above for now. Then later on once WHMCS is running navigate to `System Logs \u003e Admin Log` and you'll see IP Address. It should look something like `172.18.0.2` or similar. We're interested in the second number. So if the IP shown was `172.18.0.2` the subnet that should be set as: `172.18.0.0/16`. Restart and check the logs again, this time your real IP should be displayed.\n\n\u003cb\u003eStart docker compose\u003c/b\u003e\u003cbr /\u003e\nInside of `whmcs/compose/` run the command below. This will start WHMCS and rest of the services.\n ```\ndocker compose up -d\n ```\nLatest stable version of WHMCS should be automatically downloaded to `whmcs/data/whmcs` using WHMCS public API. Now you can navigate to `your-domain.com/install` and follow the installation insturctions. \n\n| Field             | Default value                 |\n| ----------------- | ----------------------------- |\n| License Key       |                               |\n| Database Host     | mysql                         |\n| Database Username | whmcs                         |\n| Database Password | Found in `whmcs/compose/.env` |\n| Database Name     | whmcs                         |\n\n\u003e [!TIP]  \n\u003e You can automate majority of configuration by using post-install script. You can run the script by using the command below, once you reach screen asking you to delete install directory. Steps marked with `[automated by script]` can be ignored if you choose to run the script. You can inspect the script itself at `docker-images` branch.\n\nNavigate to `whmcs/compose/` and run command below. Proceed with steps without `[automated by script]` tag.\n```sh\ndocker compose exec nginx sh -lc '/usr/local/bin/whmcs-post-install-config.sh'\n```\nIf you choose not to run the script, complete all the steps below manually.\n\n# 🔒 Security Hardening\nMake sure to complete all of the steps below! Once completed, you should be ideally left with two warning and none \"Needing Attention\" complaints inside \"System Health\" tab. One warning complaining about it running Nginx instead of Apache (this is safe to ignore). The other complaining about usage of default template names. This is also safe to ignore, but linked documentation should be read if you plan on customizing templates to follow the best practices.\n\n## Setting correct URL\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Further_Security_Steps#Enable_SSL) \u003cbr /\u003e\nSometimes the URL in admin panel might be using http instead of https which may cause a warning for invalid SSL certificate.\nIn the WHMCS panel navigate to `System Setting \u003e General Settings` and make sure `Domain` and `WHMCS System URL` are using https.\n\n## Setting update folder\nOfficial source: [help.whmcs.com](https://help.whmcs.com/m/updating/l/678178-configuring-the-temporary-path) \u003cbr /\u003e\nSetting update folder will allow you to automatically update WHMCS in the future. Similar to file storage the update folder will be located above the web root inside `whmcs_storage` directory.\nNavigate to `Automation Status (gear icon) \u003e Update WHMCS \u003e Configure Update Settings` and set the directory to `/var/www/whmcs_storage/whmcs_updater_tmp_dir`\n\n## Moving Files Above Web Root\nMoving files above web root is a recommended practice by official WHMCS documentation. This is fairly easy to do using docker volumes. \nThe volume `whmcs_storage` is used for this exact purpose, directories have been already created so all you need to do is change them in the admin panel.\n\n### File Storage\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Further_Security_Steps#File_Storage) \u003cbr /\u003e\nNavigate to `System Setting \u003e Storage Settings` under `Configurations` add listed local storage:\n| Path                                        |\n|---------------------------------------------|\n| /var/www/whmcs_storage/downloads            |\n| /var/www/whmcs_storage/attachments          |\n| /var/www/whmcs_storage/attachments/projects |\n\nNavigate to `Settings` tab and replace the old paths with the newly added ones.\n\n### Templates Cache `[automated by script]`\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Further_Security_Steps#Templates_Cache) \u003cbr /\u003e\nNavigate to `whmcs/data/whmcs/configuration.php` and change path for `$templates_compiledir` to `/var/www/whmcs_storage/templates_c`\n\n### Crons Directory `[automated by script]`\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Further_Security_Steps#Move_the_Crons_Directory) \u003cbr /\u003e\n1. Navigate to `whmcs/data/whmcs` and move `crons` directory to `whmcs/data/whmcs_storage`. \u003cbr /\u003e\n2. Navigate to `whmcs/data/whmcs_storage/crons` and edit `config.php.new`, inside the config uncomment the `whmcspath` option and set the new path to `/var/www/html/`. \u003cbr /\u003e\n3. Rename the `config.php.new` to `config.php`. \n4. Navigate to `whmcs/data/whmcs/configuration.php` and add this line at the bottom of the configuration `$crons_dir = '/var/www/whmcs_storage/crons/';`\n\nIf done correctly, crons should be now located outside web root and system set to look for new crons location as recommended by WHMCS.\n\n## Changing Configuration Permissions `[automated by script]`\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Further_Security_Steps#Secure_the_configuration.php_File) \u003cbr /\u003e\nNavigate to `whmcs/data/whmcs/` and run \n```\nsudo chmod 400 configuration.php\n```\n\n## eMail Import Cron (optional)\nOfficial source: [docs.whmcs.com](https://docs.whmcs.com/Email_Importing) \u003cbr /\u003e\nNavigate to `whmcs/compose` and edit `docker-compose.yml`, inside the file uncomment the two commands under the ofelia-labels.\u003cbr /\u003e\nRebuild stack with `docker compose down \u0026\u0026 docker compose up -d`.\n\n# 🐛 Known issues\n\n# 📝 Planned\n- Create and test an alternative installation with Apache web server\n- (Done) Create a ready to deploy Dokploy docker compose example\n\n# 📜 Credits\n- Logo created by Wob - [Dribbble.com/wob](https://dribbble.com/wob)\n- Inspired by other similar projects [fauzie/docker-whmcs](https://github.com/fauzie/docker-whmcs), [cloudlinux/kd-whmcs](https://github.com/cloudlinux/kd-whmcs) and [darthsoup/docker-whmcs](https://github.com/darthsoup/docker-whmcs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedythecow%2Fdocker-whmcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedythecow%2Fdocker-whmcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedythecow%2Fdocker-whmcs/lists"}