Persistent Storage

📦 Persistent Storage

This page explains how Uptimer stores data and loads configuration, and how to persist them properly in Docker setups.

🗂️ Docker image filesystem

/
├── app
│    ├── configs # 
│    │    └── default.yml # default configuration file 
│    └── uptimer  # application binary, entry point
├── data  # data_dir, mount it to keep data files

• Uptimer uses two main directories inside the container:

  • /app/configs/ — configuration files (default config lives here)
  • /data/ — persistent data directory for worker and server files, databases, and identities

• You must mount these directories from the host to keep data persistent and survive container restarts.

📝 Configuration File

• Uptimer default dev config inside image is /app/configs/default.yml

Copy config from image

mkdir -p ~/.uptimer
docker create --name temp-uptimer myuptime/uptimer
docker cp temp-uptimer:/app/configs/default.yml ~/.uptimer/config.yml
docker rm temp-uptimer

Mount config

Edit ~/.uptimer/config.yml as needed, then run:

docker run -p 2517:2517 \
-v "$HOME/.uptimer/config.yml:/app/configs/config.yml" \
myuptime/uptimer  dev

Mount config with custom name

docker run -p 2517:2517 \
-v "$HOME/.uptimer/custom-config.yml:/app/configs/custom-config.yml" \
myuptime/uptimer  \
--cfg /app/configs/custom-config.yml dev

Where:

• --cfg is a global flag (optional — uses configs/default.yml by default)
• dev is the command to run

📁 Data directory (/data)

• This directory contains crucial files for worker identity and server data.
• Default location inside container: /data/
• Controlled by config or environment variable general.data_dir (YAML) or UPTIMER__GENERAL__DATA_DIR (ENV)

general:  # top level config property
  data_dir: /data/  # default value for docker, env: UPTIMER__GENERAL__DATA_DIR=/data/

📁 Worker Files to Persist

• worker.pem — worker identity certificate
• worker.uid — worker unique ID

Backing up these files + your config file is enough to clone or restore a worker.

🧳 Using Subfolders for Data

You can organize multiple worker instances or configs under /data subfolders:

/var/lib/uptimer/data/
├── first
├── second

Specify which subfolder to use via environment:

docker run -p 2517:2517 \
  -v /var/lib/uptimer/data:/data \
  -e UPTIMER__GENERAL__DATA_DIR=/data/first \
  -e UPTIMER__SERVER__DB__DSN=sqlite3:///data/first/server.db \
  -e UPTIMER__WORKER__DB__DSN=sqlite3:///data/first/worker.db \
  myuptime/uptimer

Generate worker data files with:

docker run -p 2517:2517 \
  -v /var/lib/uptimer/data:/data \
  -e UPTIMER__GENERAL__DATA_DIR=/data/second \
  myuptime/uptimer worker init

📁 Server files

• server.pem and server.uuid — server identity and secrets
• Can be regenerated if compromised (will invalidate UI sessions)

Initialize or re-generate:

docker run -p 2517:2517 \
  -v /var/lib/uptimer/data:/data \
  myuptime/uptimer server init

You can add --force flag to regenerate em

🛢️ Database Configuration

• Worker database: usually sqlite3, stored inside data dir — no extra setup needed
• Server database: PostgreSQL recommended for production, SQLite3 for small setups

Worker and server can use the same database because their tables use distinct prefixes

Default settings are:

server:  # Optional for worker configuration
  db:
    dsn: sqlite3:///data/server_db.sqlite   # env: UPTIMER__SERVER__DB__DSN=sqlite3:///data/server_db.sqlite
worker:  # Optional for server configuration
  db:
    dsn: sqlite3:///data/worker_db.sqlite   # env: UPTIMER__WORKER__DB__DSN=sqlite3:///data/worker_db.sqlite

Schema migrations happen automatically on startup.

Example: Minimalistic with persistent storages

git clone https://github.com/myuptime-info/uptimer-docs.git
cd uptimer-docs/examples/dev-persistent-no-config
docker compose up 

📌 Summary

To keep Uptimer data persistent:

• Mount the /data directory from host to container
• Optionally mount your custom config file to /app/configs/config.yml
• Use environment variables to override config values as needed
• You can organize data in subfolders and specify the path via UPTIMER__GENERAL__DATA_DIR
• PostgreSQL is recommended for the server for better performance and reliability.

➡️ Next Steps

After configuring persistent storage, proceed to Authentication setup.