Install guide

Install the self-hosted Ovumcy web product

Use this guide only for the full self-hosted Ovumcy web product. Download the release-pinned Docker Compose files, set a strong application secret, start the stack, and check `/healthz`. If someone wants the local-first mobile app, self-hosted sync for the app, or managed hosting, those are different product paths.

The supported first install path is intentionally narrow: a full self-hosted web deployment with Docker Compose, a strong secret, persistent storage, and a health check before any public exposure.

Self-host overview Ovumcy App Managed hosting

Choose first

Pick the right product path before running server commands

This page is intentionally only for the full self-hosted web deployment. If that is not the path you actually want, one of the options below will save time immediately.

No server wanted

Start with Ovumcy App when the goal is private cycle tracking without operating infrastructure. Core app use works without an account, sync, or a server.

Open ovumcy.app

Keep the app, add your own sync server

Use the self-hosted sync backend when the mobile app stays primary but backup, restore, and multi-device encrypted sync should run on your own infrastructure.

Review sync backend

Want managed continuity

Use managed hosting when sync and managed-only convenience matter more than operating the stack yourself. That route lives on `ovumcy.cloud`, not in these self-host docs.

Open ovumcy.cloud

Prerequisites

What is needed before first start

The supported path is narrow by design because this page documents only the full self-hosted web deployment.

A server or NAS you control

This page is for the full self-hosted web deployment, so it assumes a machine you intentionally operate instead of an app-only or managed product path.

Docker and Compose

The supported quick start assumes a host with Docker and Docker Compose available.

A place to store secrets and data

Ovumcy needs a strong `SECRET_KEY` or `SECRET_KEY_FILE` and persistent data storage for the selected database engine.

A clear deployment mode

Decide whether this is a local/private install or a public HTTPS deployment, because proxy and cookie settings change between those modes.

HowTo

Supported Docker quick start

The HTML structure below mirrors the JSON-LD `HowTo` data in the page head so both humans and search systems can follow the same install sequence.

Step
Download the release-pinned compose files

Start from an empty deployment directory and fetch the tagged `docker-compose.yml` plus `.env.example` from the current upstream release.
```
mkdir -p ovumcy && cd ovumcy
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/ovumcy/ovumcy-web/v0.8.5/docker-compose.yml
curl -fsSL -o .env \
  https://raw.githubusercontent.com/ovumcy/ovumcy-web/v0.8.5/.env.example
```
The upstream release tag stays visible in the downloaded compose file through the default `OVUMCY_IMAGE` reference.
Step
Set the application secret and review the env file

Edit `.env` once before first start. Set a strong `SECRET_KEY` or mount a secret file and point `SECRET_KEY_FILE` at the readable in-container path.
```
# required before first start:
# SECRET_KEY=<long-random-value>
# or SECRET_KEY_FILE=/run/secrets/ovumcy_secret_key

# keep the release-pinned image reference:
OVUMCY_IMAGE=ghcr.io/ovumcy/ovumcy-web:v0.8.5

# local/private baseline defaults:
HOST_BIND_ADDRESS=127.0.0.1
PORT=8080
COOKIE_SECURE=false
TRUST_PROXY_ENABLED=false
```
Keep `COOKIE_SECURE=false` and `TRUST_PROXY_ENABLED=false` for the local/private baseline until a trusted HTTPS reverse proxy is actually in front of the app.

`DEFAULT_LANGUAGE` currently supports `en`, `ru`, `es`, `fr`, and `de`.
Step
Start the stack and verify health

Launch the container, confirm the service is running, and verify the health endpoint before opening the UI.
```
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:8080/healthz
```
If the health check returns `ok`, the baseline install is up and ready for browser access on `http://127.0.0.1:8080`.
Step
Move to the dedicated reverse-proxy examples for public HTTPS

Do not expose the base `8080` app port directly to the public internet. Use the official Caddy or Nginx examples when the deployment needs a public hostname and TLS.
```
# public HTTPS baseline
COOKIE_SECURE=true
TRUST_PROXY_ENABLED=true
PROXY_HEADER=X-Forwarded-For
TRUSTED_PROXIES=<only-the-proxy-ip-or-subnet-you-control>
```
The public path keeps only the proxy on host ports `80/443`, while the app stays private on the internal network.

Verification

Checks before the deployment is trusted

A running container is not the same as a trustworthy deployment. These checks make the operator contract explicit.

Health check

Use `/healthz` after startup and again after upgrades to confirm the service is actually responding, not just that the container exists.

Persistent data

Confirm the deployment stores data on a persistent volume or database before you rely on it for real records.

Public safety

If the instance will be public, verify HTTPS termination, `COOKIE_SECURE=true`, and trusted proxy settings before inviting real users.

Alternatives

Other web deployment paths

Docker is the recommended first install for the full self-hosted web stack, but the upstream product documents several intentional alternatives inside that same operator path.

Manual install

The upstream README also documents a manual path with Go and Node.js for operators who intentionally prefer direct binary execution.

Advanced Postgres path

SQLite is the supported baseline. PostgreSQL is available through official example stacks when the operator intentionally wants a separate database runtime.

Optional OIDC sign-in

OIDC remains optional and requires HTTPS plus `COOKIE_SECURE=true`. It should be added only after the baseline deployment is already stable.

Next links

Keep the source of truth close

These links connect the install flow on this site to the current upstream repository and deeper operator documentation.

Self-host overview FAQ Self-hosted sync backend GitHub Issues Upstream README Operations guide Caddy example Nginx example