Install on a VPS (Dokploy)

Dokploy is a dashboard you install on your own server. It builds and runs Threadline from a Git repository, gets your HTTPS certificate, and redeploys with one click. It uses the same docker-compose.yml as the Docker guide, so you get MySQL, Redis, Qdrant, a queue worker and the scheduler. If you do not use Dokploy, follow that guide instead.

What you need

• A VPS with Dokploy already installed (see Dokploy's own install guide). We recommend at least 2 CPU cores and 4 GB of RAM, because Dokploy itself and every Threadline service run on the same server.
• A domain name with an A record pointing at the server's IP address.
• A private Git repository (GitHub, GitLab or another Git host) to hold the Threadline files. Dokploy builds from Git, so a zip file cannot be deployed directly.

Steps

1. Put the files in a Git repository. Create an empty private repository. Unzip the Threadline ZIP into an empty folder on your computer, go into that folder (the one with docker-compose.yml) and run:

   git init
   git add .
   git commit -m "Threadline"
   git branch -M main
   git remote add origin git@github.com:YOUR_ACCOUNT/threadline.git
   git push -u origin main

   The package already ignores .env. Never commit a .env file: your settings go into Dokploy in step 4.
2. Create a Compose service. In Dokploy, create a project, then Create Service → Compose. Give it a name and keep the type Docker Compose.
3. Connect the repository. Open the service's General tab. Choose your Git provider (connect GitHub, or use the Git option with a deploy key), then select the repository and branch. Set Compose Path to ./docker-compose.yml. Save.

   Use docker-compose.yml only. Do not use docker-compose.ports.yml with Dokploy: its Traefik reaches the app over the Docker network, and publishing a port would only expose it.

4. Add your settings. Open the Environment tab and paste the block below, then save. Dokploy writes it to the .env file the Compose file reads. On your own computer, generate the key and the two passwords first:

   echo "base64:$(openssl rand -base64 32)"
   openssl rand -hex 16
   openssl rand -hex 16

   APP_NAME=Threadline
   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=PASTE_THE_KEY_HERE
   APP_URL=https://your-domain.com
   
   SERVER=vps
   
   DB_DATABASE=threadline
   DB_USERNAME=threadline
   DB_PASSWORD=PASTE_FIRST_PASSWORD
   DB_ROOT_PASSWORD=PASTE_SECOND_PASSWORD

   Common mistakes: leaving APP_ENV=local or APP_DEBUG=true (it exposes private settings and developer-only pages), using root as DB_USERNAME (MySQL refuses to start), forgetting DB_ROOT_PASSWORD, and using symbols such as $ or # in passwords. The Compose file sets the database host, Redis, Qdrant, queue, cache and session settings for you, so leave those out. Set up email later in the Owner area (see Mail & Email Templates).

5. Add the domain. Open the Domains tab and add one:
   • Host: your domain, for example support.example.com
   • Service Name: app
   • Container Port: 80
   • HTTPS: on, with the Let's Encrypt certificate
   Save. Dokploy's Traefik handles the certificate.
6. Deploy. Click Deploy and watch the Deployments tab. The first build takes several minutes. When it finishes, the service shows running, with six containers: app, queue, scheduler, mysql, redis and qdrant. Open the app container's logs: the database migrations run first, then nginx starts.
7. Create the Owner account. Open https://your-domain.com. Threadline skips the requirements and database steps and shows one Create owner account screen. Fill it in, then log in.

There is no cron job to add in this mode: the scheduler container runs scheduled tasks and the queue container sends messages.

After you install

• Connect an AI provider. See AI Provider Setup.
• Set up email in Mail & Email Templates.
• Check Cron & Health to confirm the scheduler is running.

Updating

Replace the files in your repository with the new version (keep your settings in Dokploy, not in the repository), commit and push, then click Deploy. You can also turn on auto-deploy so every push redeploys. Database changes are applied automatically when the app container starts. The uploader in Maintenance is not used in this mode. After a deploy, check the Is everything on the new version? card on the App Update page. Full steps are in Updating Threadline.

Backups

Your data lives in three volumes:

• mysql_data: the database. Back this up.
• storage_data: uploaded files, knowledge-base documents and in-app backups. Back this up.
• qdrant_data: the vector index. It can be rebuilt from your documents, but that costs AI time and tokens, so back it up too.

Set up scheduled backups in Dokploy to an off-server destination such as S3-compatible storage. The options differ between Dokploy versions, so use Dokploy's own backup pages for the service. To take a one-off database dump, open the mysql container's terminal in Dokploy and run:

mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" > /tmp/threadline.sql

If something goes wrong

More in Troubleshooting & FAQ.