Setting Up A Kowloon Server

Setting Up Your Own Kowloon Server

This guide assumes you can open a terminal, log into a remote server over SSH, and run commands. You do not need to be a Linux expert or know anything about Docker.

What you will need before you start

A server or VPS. Kowloon runs on any Linux server or Mac running macOS 13 or later. A $6/month VPS from DigitalOcean, Linode, or Hetzner is fine for a small community. You will need at least 1 GB of RAM and 20 GB of disk. Two gigabytes of RAM is more comfortable.

Docker. The installer handles everything through Docker. On Ubuntu and Debian the installer will install Docker for you automatically. On any other platform, install Docker Desktop (Mac or Windows) or Docker Engine (Linux) from https://docs.docker.com/get-docker/ before running the installer.

A domain name pointing at your server. Something like kowloon.example.com. The installer sets up HTTPS automatically and needs a real hostname to do that. It cannot run on a bare IP address.

An SMTP relay for outgoing email. Kowloon sends invite emails, password reset links, and admin notifications. You can use any SMTP service — Resend, Mailgun, Postmark, Amazon SES, or whatever you have. You will need the hostname, port, username, and password. The installer has a built-in test button so you can confirm your settings work before finishing setup.

Running the installer

Log into your server and run this command:

curl -fsSL https://raw.githubusercontent.com/jzellis/kowloon/main/install.sh | bash

The installer will:

Install Docker automatically if you are on Ubuntu or Debian and it is not already installed
Open a browser-based setup wizard where you enter your domain, admin credentials, and email settings
Pull and start all Kowloon services in Docker containers
Request an HTTPS certificate from Let's Encrypt automatically

The whole process takes about five to ten minutes, most of which is downloading container images. When it finishes, your server will be running at the domain you configured.

Installing to a custom directory

By default, Kowloon puts its configuration files in ~/kowloon. If you want them somewhere else — for example /opt/kowloon on a shared server — pass the path as an argument:

curl -fsSL https://raw.githubusercontent.com/jzellis/kowloon/main/install.sh | bash -s -- /opt/kowloon

You can also set the KOWLOON_DIR environment variable before running the script:

export KOWLOON_DIR=/opt/kowloon
curl -fsSL https://raw.githubusercontent.com/jzellis/kowloon/main/install.sh | bash

The directory you choose is where docker-compose.yml and .env are written. Docker data (database, uploaded files) lives in named Docker volumes and is not affected by this path.

First login

Open your browser and go to your domain. Click Log In and use the admin username and password you set during installation.

Go to Admin > Settings to fill in your server's name, description, and contact email. These appear on your server's public-facing homepage.

To invite people, go to Admin > Invites. Generate invite links and send them to whoever you want to join. By default, registration requires an invitation.

Managing your own SSL and reverse proxy

By default, Kowloon uses Caddy to handle HTTPS automatically. If you already have a reverse proxy (Nginx, Traefik, Cloudflare Tunnel, Caddy running elsewhere), open Advanced settings in the setup wizard and check I'll manage my own SSL and reverse proxy. You will also be asked for the port Kowloon should listen on (default: 3000).

When this option is enabled:

No Caddy container is included in the Docker stack
The Kowloon application container exposes the chosen port directly on your host
No Caddyfile is written

You are then responsible for:

Terminating TLS (your proxy handles HTTPS)
Forwarding traffic to localhost:<port>

Example Nginx config:

server {
    listen 443 ssl;
    server_name kowloon.example.com;

    ssl_certificate     /etc/letsencrypt/live/kowloon.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kowloon.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 100m;
        proxy_read_timeout 120s;
    }
}

Example Caddy config (if running Caddy yourself):

kowloon.example.com {
    reverse_proxy localhost:3000
}

Backups

Go to Admin > Settings > Backup and click Create Backup. Kowloon will take a full snapshot of your database and all uploaded files. You can download the archive from that same interface.

Backups expire after 48 hours. Get into the habit of creating one before making any significant changes to your server.

To restore from a backup, use the Restore section on the same page. Upload the .tar.gz file, confirm the warning, and click Restore. The server stays up during the restore.

Updating Kowloon

SSH into your server and run:

cd ~/kowloon
docker compose pull
docker compose up -d

Replace ~/kowloon with your install directory if you chose a custom path. This pulls the latest container images and restarts the services. Always create a backup before updating.

Viewing server logs

If something is not working, go to Admin > Logs. You will see a live tail of the server activity log. Use the Download button to save it as a file.

Known limitations in this alpha version

No cross-platform federation yet. Kowloon servers can federate with each other, but ActivityPub interop with Mastodon and other platforms is not a current priority.

No mobile app yet. The mobile app is in development.

No direct messages yet. Private one-on-one messaging is planned but not available in this release.

jzellis/Kowloon-Alpha-setup.md

Select an option

No results found