Install with Docker Compose

The most direct installation: two containers on a server you manage, with Docker and its Compose plugin. Read the installation overview first if you are still choosing a method.

Create a compose file

Create a compose.yaml file:

services:
  uptime-kotlin:
    image: ghcr.io/theomeunier/uptime-kotlin:latest
    container_name: uptime_kotlin
    restart: unless-stopped
    mem_limit: 512m
    ports:
      - '8080:8080'
    environment:
      TZ: Europe/Paris
      QUARKUS_DATASOURCE_USERNAME: uptime-kotlin
      QUARKUS_DATASOURCE_PASSWORD: change-me
      QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://postgres:5432/uptime-kotlin
      ENCRYPTION_MASTER_KEY: change-me-32-characters-minimum-0
      MP_JWT_VERIFY_ISSUER: https://issuer.uptime-kotlin.com
    depends_on:
      - postgres

  postgres:
    image: postgres:18.6-alpine
    container_name: uptime_kotlin_database
    restart: unless-stopped
    environment:
      POSTGRES_DB: uptime-kotlin
      POSTGRES_USER: uptime-kotlin
      POSTGRES_PASSWORD: change-me
    volumes:
      - ./storage-db:/var/lib/postgresql

Set your secrets

Replace ENCRYPTION_MASTER_KEY with the output of this command, and change both change-me passwords:

openssl rand -base64 32

Keep this key somewhere safe. It encrypts the stored secrets (notification tokens, database passwords of your monitors) and a lost key cannot be recovered. To change it later, see Rotate the master key.

Start the stack

docker compose up -d

Open http://localhost:8080 and create the first account.

Upgrade from PostgreSQL 17

Earlier versions of this guide used postgres:17.4-alpine with the data under /var/lib/postgresql/data. PostgreSQL 18 cannot open the files of version 17, and its image keeps the data under /var/lib/postgresql. You can keep your current postgres service, or move the data with a dump.

Stop the application and dump the database:

docker compose stop uptime-kotlin
docker compose exec postgres pg_dump -U uptime-kotlin uptime-kotlin > backup.sql
docker compose down
mv storage-db storage-db-17

Update the postgres service of compose.yaml as shown above, start it alone, and wait a few seconds for it to accept connections. Then load the dump and start the stack:

docker compose up -d postgres
docker compose exec -T postgres psql -U uptime-kotlin uptime-kotlin < backup.sql
docker compose up -d

Keep storage-db-17 and backup.sql until you have checked your monitors and history. The ENCRYPTION_MASTER_KEY does not change.

Good to know

Behind a reverse proxy, forward every path to port 8080 and allow a 300 s read timeout for exports.

All the environment variables are listed on the configuration page. Next, create your first monitor.