Skip to content
flexcal Documentation

Docker

The image is published to docker.io/flexcal/flexcal, built for linux/amd64 and linux/arm64. Use the dev tag for the current default branch, or a semver tag (for example v6.2.0) for a release.

Terminal window
docker pull docker.io/flexcal/flexcal:dev

Requirements

Section titled “Requirements”

docker and docker compose must be installed on the host. docker compose (no hyphen) is the current form of the command.

Running with Docker Compose

Section titled “Running with Docker Compose”

The docker-compose.yml lives in the flexcal repository, so start by cloning it:

Terminal window
git clone https://codefloe.com/flexcal/flexcal.git
cd flexcal

Copy the example environment file:

Terminal window
cp .env.example .env

Generate the required secrets

Section titled “Generate the required secrets”

Do not ship the placeholder secret values to production.

Generate NEXTAUTH_SECRET, the cookie encryption key:

Terminal window
openssl rand -base64 32

Generate CALENDSO_ENCRYPTION_KEY, which must be 32 bytes for AES256:

Terminal window
openssl rand -base64 24

Put both into .env:

NEXTAUTH_SECRET=<your_generated_secret>
CALENDSO_ENCRYPTION_KEY=<your_generated_key>

Web push notifications need a VAPID key pair. Without them you will see Error: No key set vapidDetails.publicKey:

Terminal window
npx web-push generate-vapid-keys
NEXT_PUBLIC_VAPID_PUBLIC_KEY=<your_public_key>
VAPID_PRIVATE_KEY=<your_private_key>

Everything else can usually stay as shipped, see Configuration for the full list.

Start the stack

Section titled “Start the stack”

Optionally pre-pull the images:

Terminal window
docker compose pull

The full stack (Postgres, the flexcal web app and Prisma Studio):

Terminal window
docker compose up -d

The web app and Prisma Studio against an external database, with DATABASE_URL pointing at it:

Terminal window
docker compose up -d flexcal studio

Only the web app:

Terminal window
docker compose up -d flexcal

Drop -d to run attached when debugging.

First run

Section titled “First run”

Open http://localhost:3000, or whatever NEXT_PUBLIC_WEBAPP_URL points at. A setup wizard runs the first time and creates your first user.

The wizard’s “Connect your Calendar” step looks mandatory but is not: navigate straight to <NEXT_PUBLIC_WEBAPP_URL>/event-types to skip it. Calendar integrations can be added later under Settings → Integrations.

Updating

Section titled “Updating”
Terminal window
docker compose down
docker compose pull

Reconcile your .env against the current .env.example, then:

Terminal window
docker compose up -d

Migrations and app-store seeding on boot

Section titled “Migrations and app-store seeding on boot”

By default, the container applies database migrations and seeds the app store every time it starts. That is correct for Docker Compose, which has nowhere else to run them.

For deployments that migrate once per release (the Helm chart does this in a pre-upgrade Job), set both flags so replicas do not race each other:

SKIP_DB_MIGRATIONS=1
SKIP_APP_STORE_SEED=1

Building the image yourself

Section titled “Building the image yourself”

See Container images.