Production setup

This guide shows how to install Quollix for production use on a LAN or an internet-facing server. The examples assume a base domain such as example.com, referred to below as <base-domain>.

1. Choose a server: for example, a virtual private server (VPS) from a hosting provider or a physical server at home. For provider-specific VPS notes, see the Hetzner Cloud server setup guide.
2. Install Docker: install Docker on the server, see Getting started.
3. Configure DNS: Decide which base domain Quollix should use. For example, if you want apps to be available at nextcloud.example.com and vaultwarden.example.com, the base domain is example.com. Quollix itself will be available at quollix.example.com. See Base Domain for details.

Create a single wildcard DNS record that points to the IP address of the Quollix server:

*.example.com  A  <server-ip>

If you use IPv6, also configure the corresponding wildcard AAAA record.

For LAN setups, you can host your own DNS server or use your router’s DNS server if supported. For public IP addresses, you usually need a public DNS server.

4. Create the Docker Compose file: add a docker-compose.yml file:

services:
  quollix:
    image: quollix/quollix:latest
    container_name: quollix_quollix_quollix
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /tmp:/tmp
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

If you want to run Quollix behind a reverse proxy, read the reverse proxy setup guide before starting the container.

If you want to configure the initial administrator account, read the initial admin account guide before starting the container.

5. Start Quollix: run the following command in the same directory as docker-compose.yml:

sudo docker compose up -d

6. Open the web interface: visit https://quollix.<base-domain>. Quollix initially uses a self-signed certificate, so your browser will show a certificate warning. Continue only if you trust the network path to the server. A trusted certificate is configured later in this guide.
7. Find the initial password: Quollix logs a random initial password on first startup:

sudo docker logs quollix_quollix_quollix | grep "initial admin password"

8. Sign in: use the username administrator with the generated password from the logs.

After signing in, open the Settings page in Quollix.

9. Set the base domain: set Base Domain to <base-domain>, and save.
10. Set up a certificate: in the Certificates section, start the challenge to generate a wildcard certificate, then follow the instructions until you see a success message. Restart the browser because browsers usually cache the old self-signed certificate.

Visiting https://quollix.<base-domain> should now use a certificate signed by Let’s Encrypt.

Troubleshooting

Missing Initial Password

If you accidentally recreate the container before copying the initial password, the existing database volume may keep the old administrator account while the password is no longer visible in the logs. In that case, reset the initial installation state. This deletes the Quollix database and starts from a clean installation:

sudo docker compose down
sudo docker volume rm -f quollix_postgres_data

Then start Quollix again:

sudo docker compose up -d

Next Steps

The Self-Hosting section provides additional guidance for running Quollix in a self-hosted environment.