Self-Hosted Project Management Software: AlianHub on Docker

AlianHub is open-source, self-hosted project management software, and the fastest way to run it is Docker Compose. Three commands on any host with Docker give you a working instance on port 4000. This guide walks through install, first run, configuration, HTTPS, upgrades and backups, using the same steps as the official admin guide.

Why choose self-hosted project management software

Hosted tools are convenient, but they put your tasks, comments and files on someone else's servers. Self-hosting keeps that data on infrastructure you control.

With AlianHub you also get:

• No per-seat pricing. It is free and open source under AGPL-3.0.
• Full project features. Tasks, sprints, Board, List, Calendar, Gantt and Workload views, docs, automations and time tracking. See the features page.
• AI you choose. Bring your own LLM key, or let people connect their own AI over MCP. Nothing requires AI.
• Multi-architecture images. Docker images are published on GHCR for amd64 and arm64.

What you need before you start

For a production instance you will also want a domain name and a reverse proxy for HTTPS, covered below.

Step 1: Install AlianHub with Docker Compose

Download the compose file, generate a secret, and start the stack:

curl -O https://raw.githubusercontent.com/aliansoftwareteam/AlianHub-Project-Management-System/main/docker-compose.yml
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
docker compose up -d

Then open http://<your-host>:4000. A fresh database sends you to the setup page.

What the compose file runs

The stack is small and easy to reason about:

• app: AlianHub on Node 20, with the built web app served by the API.
• mongo: MongoDB 7, on the internal network only.
• alianhub_mongo_data: a volume for the databases.
• alianhub_storage: uploaded files, when STORAGE_TYPE=server (the default in the image).
• alianhub_logs: rotating logs, readable from Settings › Instance › Logs.
• alianhub_backups: archives written by the Backups page.

The container becomes healthy once /health answers 200, which needs the database. Keep MONGODB_URL as the server address only, such as mongodb://mongo:27017; the app creates one database per company under it.

Keep JWT_SECRET stable

Secrets stored in the app are encrypted with a key derived from JWT_SECRET. If you rotate it, stored secrets become unreadable and read as unset. Back up your .env file alongside your data.

Step 2: Complete the first run

With an empty database, every address redirects to /#/setup. The page checks the database first. If it cannot connect, it shows the exact error and how to fix it.

The setup form asks for:

1. The owner account: name, email and password.
2. The workspace name.
3. Optionally, what your team mainly does, which picks the sample content.
4. Whether to start with a sample project.

Under a minute later you are logged in as the owner. This account is the only one that sees Settings › Instance. Everyone else is invited from Settings › Members. Setup refuses to run again once a user exists.

Step 3: Configure mail, storage, AI and sign-in

Every operational setting lives in Settings › Instance › Settings, grouped as General, Mail, Storage, AI, Sign-in, Calling and Security. Groups that can be tested have a Test button that tries your values before you save.

A key set in .env or the container environment wins. It shows as env in the page and must be changed where it is set, followed by a restart.

The settings that matter first

• General: WEBURL (the address people open) and APIURL (the same, with a trailing slash).
• Mail: SMTP or Resend. Without mail, invitations and password resets cannot be sent.
• Storage: keep files on disk with STORAGE_TYPE=server, or use any S3-compatible bucket. Changing the driver needs a restart and does not move existing files.
• AI: LLM_PROVIDER (openai, anthropic or deepseek) plus the matching key and model. Read more on the AI page.
• Sign-in: Google, GitHub and GitLab, each with a switch, client id and secret.

Step 4: Put HTTPS in front of it

Place a reverse proxy with a certificate in front of port 4000. Caddy, nginx and Traefik all work, and any of them can obtain a Let's Encrypt certificate. A minimal Caddyfile:

your.host {
  reverse_proxy localhost:4000
}

Then:

1. Set WEBURL=https://your.host and APIURL=https://your.host/.
2. Set TRUST_PROXY=1 so rate limiting sees real client addresses.
3. Make sure the proxy forwards WebSocket upgrades for /socket.io/.

HTTPS is not optional in production. Cookies are marked Secure, so logging in over plain HTTP with NODE_ENV=production fails by design, and audio and video calls need a secure context. Connecting outside AI apps by address also needs an https origin.

Step 5: Upgrade safely

Settings › Instance › Upgrade shows your running version, the latest GitHub release, newer changelog entries and the migration state. Take a backup first, then pull and restart:

docker compose pull && docker compose up -d

Migrations run automatically at boot before the server starts listening. A failed migration does not stop the server: /health reports it, the Upgrade page shows which step failed and why, and the next boot retries it.

Step 6: Back up and restore

Settings › Instance › Backups writes a .tar.gz archive to the backups volume. It contains every collection of every database, and optionally your uploaded files. Download archives and keep at least one copy off the host.

To script backups, set INSTANCE_ADMIN_KEY in .env and call the API from a cron job:

curl -s -X POST -H "adminkey: $INSTANCE_ADMIN_KEY" http://localhost:4000/api/v2/instance/backups -H 'content-type: application/json' -d '{}'

A restore takes a safety backup first, switches the API to maintenance, replaces the data and reruns migrations. Restore archives from the same or an older version, never a newer one. Test restores on a separate machine, not as a second Compose project on the same host, because the volumes have fixed names and would attach to live data.

Troubleshooting

Settings › Instance › Health is the first place to look. Cards for database, storage, mail, migrations, automation queue, backups and scheduled jobs turn amber or red when something needs attention. The full reference is in the admin guide.

FAQ

Can I self-host AlianHub without Docker?

Yes. Clone the repository and run npm run setup with Node.js 20 and MongoDB 6 or 7 available. Run it under a process manager such as pm2 or systemd in production.

Does AlianHub run on ARM servers?

Yes. The Docker images on GHCR are built for both amd64 and arm64.

Do I need an AI API key?

No. Nothing in the product requires AI. Add an LLM key later if you want AI Assist, or let people connect their own AI over MCP.

How do I move existing work into my new instance?

If you are coming from ClickUp, export CSV or Excel and import it under Settings › Import & export. The moving from ClickUp guide covers each step.

Start your own instance

Self-hosted project management software should be quick to stand up and easy to keep running, and AlianHub is designed for both. Try it first at demo.alianhub.com, then run the three Docker commands above on your own server. If you would like help with hosting or support, get in touch.