diff --git a/.env.example b/.env.example index 2d7d679..78dd493 100644 --- a/.env.example +++ b/.env.example @@ -4,10 +4,20 @@ APP_URL=http://localhost:5200 API_URL=http://localhost:5100 +OPENCASHFLOW_VERSION=v0.1.0-preview.2 + JWT_SECRET=change-me-use-a-random-secret-with-at-least-64-characters # Docker Compose uses its internal db hostname. -DEFAULT_CONN_STRING=Host=db;Database=opencashflow;Username=postgres;Password=postgres +POSTGRES_DB=opencashflow +POSTGRES_USER=postgres +POSTGRES_PASSWORD=change-me-use-a-strong-database-password +DEFAULT_CONN_STRING=Host=db;Database=opencashflow;Username=postgres;Password=change-me-use-a-strong-database-password + +# Host ports exposed by docker-compose.release.yml. +WEBAPP_PORT=5200 +API_PORT=5100 +POSTGRES_PORT=5432 # Explicit startup behavior. AUTO_MIGRATE=true diff --git a/Docs/assets/setup/docker-compose-stack.svg b/Docs/assets/setup/docker-compose-stack.svg new file mode 100644 index 0000000..31718bc --- /dev/null +++ b/Docs/assets/setup/docker-compose-stack.svg @@ -0,0 +1,38 @@ + + OpenCashFlow Docker Compose stack + Three containers connected by Docker Compose: PostgreSQL database, API, and WebApp. + + + + + + + + Docker Compose release stack + Compose creates a private network and starts three services. + + + + db + PostgreSQL + Persistent volume: pgdata + + + + api + OpenCashFlow API + Health: localhost:5100 + + + + webapp + Browser UI + Open: localhost:5200 + + + + Host: db + Host: api + diff --git a/Docs/assets/setup/env-configuration.svg b/Docs/assets/setup/env-configuration.svg new file mode 100644 index 0000000..1fb4468 --- /dev/null +++ b/Docs/assets/setup/env-configuration.svg @@ -0,0 +1,27 @@ + + Edit .env configuration + A configuration file with important values highlighted: app URL, JWT secret, database password, SMTP. + + + + + Copy .env.example to .env, then edit it + The release stack reads runtime settings from your local .env file. + + + APP_URL=http://localhost:5200 + JWT_SECRET=change-this-before-use + POSTGRES_PASSWORD=change-this-too + SMTP_HOST= + OPENCASHFLOW_VERSION=v0.1.0-preview.2 + + + Must change + JWT secret and DB password. + + + Optional for first run + SMTP can stay empty initially. + diff --git a/Docs/assets/setup/first-login-password-change.svg b/Docs/assets/setup/first-login-password-change.svg new file mode 100644 index 0000000..9611db1 --- /dev/null +++ b/Docs/assets/setup/first-login-password-change.svg @@ -0,0 +1,34 @@ + + First login requires password change + After login with the temporary password, the administrator must change it before normal use. + + + + + + + + First login forces a password change + The temporary password is only a bootstrap credential. + + + + Login + Use temporary password + + + + + + Change password + Required before normal use + + + + + + Ready + Open dashboard + diff --git a/Docs/assets/setup/first-run-setup.svg b/Docs/assets/setup/first-run-setup.svg new file mode 100644 index 0000000..fb1b261 --- /dev/null +++ b/Docs/assets/setup/first-run-setup.svg @@ -0,0 +1,25 @@ + + First-run setup wizard + The first-run setup form creates the first company and administrator. + + + + + Fresh database redirects to /Setup + The wizard creates application data. It does not provision PostgreSQL infrastructure. + + + + OpenCashFlow Setup + + Company name + + Admin email + + Language / Currency / Timezone + + + Create + diff --git a/Docs/assets/setup/generated-password-once.svg b/Docs/assets/setup/generated-password-once.svg new file mode 100644 index 0000000..526eb2b --- /dev/null +++ b/Docs/assets/setup/generated-password-once.svg @@ -0,0 +1,20 @@ + + Generated password shown once + The generated administrator password is displayed once and must be stored immediately. + + + + + Temporary admin password is shown exactly once + OpenCashFlow stores only the hash. The plaintext value is not replayed after setup. + + + + Setup complete + Store this generated password now. + + ••••-generated-once-•••• + Shown once + diff --git a/Docs/releases/0.1.0-preview.2.md b/Docs/releases/0.1.0-preview.2.md index fe87f54..c04a272 100644 --- a/Docs/releases/0.1.0-preview.2.md +++ b/Docs/releases/0.1.0-preview.2.md @@ -94,6 +94,18 @@ http://localhost:5200 On a fresh database, the WebApp redirects to `/Setup`. +For a step-by-step explanation of the release stack, `.env`, startup, updates, backups, and first-run setup, see: + +```text +Docs/setup/docker-compose-release-install.md +``` + +For a visual walkthrough, see: + +```text +Docs/setup/docker-compose-visual-guide.md +``` + ## Docker Image Publishing Preview tags matching `v*-preview.*` publish Docker images through GitHub Actions: diff --git a/Docs/setup/docker-compose-release-install.md b/Docs/setup/docker-compose-release-install.md new file mode 100644 index 0000000..471fc25 --- /dev/null +++ b/Docs/setup/docker-compose-release-install.md @@ -0,0 +1,206 @@ +# Docker Compose Release Install + +OpenCashFlow preview releases are shipped as a Docker Compose stack. + +The release package is intended for local evaluation and early self-hosted testing. It is not a production-ready deployment profile. Before exposing OpenCashFlow to other users or networks, review the hardening guidance in `Docs/ops/`. + +For a picture-based walkthrough, see `Docs/setup/docker-compose-visual-guide.md`. + +## Stack Layout + +The release stack runs three services: + +- `db`: PostgreSQL database. +- `api`: OpenCashFlow API service. +- `webapp`: OpenCashFlow WebApp service. + +These are separate containers because they have different responsibilities: + +- PostgreSQL owns persistent data. +- The API owns migrations, application logic, authentication, authorization, and data access. +- The WebApp owns browser-facing pages and talks to the API over the internal Compose network. + +Keeping them separate makes the runtime easier to reason about, update, inspect, and eventually operate behind a reverse proxy. + +## How Docker Compose Connects The Services + +Docker Compose creates a private network for the stack. + +Inside that network: + +- the API connects to PostgreSQL using the hostname `db`; +- the WebApp connects to the API using the hostname `api`; +- users access the WebApp through `http://localhost:5200`; +- the API health endpoint is exposed on `http://localhost:5100/health`. + +The public browser never connects directly to the `db` container. + +## Download And Start + +Download the preview package: + +```bash +curl -LO https://github.com/Reckonry/OpenCashFlow/releases/download/v0.1.0-preview.2/OpenCashFlow-0.1.0-preview.2.tar.gz +# or: +# wget https://github.com/Reckonry/OpenCashFlow/releases/download/v0.1.0-preview.2/OpenCashFlow-0.1.0-preview.2.tar.gz +``` + +Extract it: + +```bash +tar -xzf OpenCashFlow-0.1.0-preview.2.tar.gz +cd OpenCashFlow-0.1.0-preview.2 +``` + +Create your local environment file: + +```bash +cp .env.example .env +``` + +Edit `.env`, then start the stack: + +```bash +docker compose -f docker-compose.release.yml up -d +``` + +Open: + +```text +http://localhost:5200 +``` + +On a fresh database, the WebApp redirects to `/Setup`. + +## What `.env` Configures + +The `.env` file is read by Docker Compose and passed to the containers as environment variables. + +Important values: + +- `APP_URL`: public WebApp URL used by redirects and links. +- `JWT_SECRET`: signing secret for authentication tokens. +- `AUTO_MIGRATE`: whether the API applies EF migrations on startup. +- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM`: optional email settings. +- `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`: database name and credentials, if you override the defaults. +- `API_PORT`, `WEBAPP_PORT`, `POSTGRES_PORT`: host ports, if you need to avoid local conflicts. +- `OPENCASHFLOW_VERSION`: image tag to run, for example `v0.1.0-preview.2`. + +The release Compose file includes local defaults for evaluation, but you should set explicit values in `.env` for any shared environment. + +## Values You Must Change Before Shared Use + +Change these before exposing the stack beyond your own local machine: + +- `JWT_SECRET`: use a long random value. Do not use the example value. +- `POSTGRES_PASSWORD`: use a real database password. +- `APP_URL`: set the actual HTTPS URL users will open. +- SMTP settings, if password reset or outbound email should work. + +Also add TLS and a reverse proxy before public exposure. Do not expose the default local evaluation stack directly to the Internet. + +## First-Run Setup + +When the database is empty, OpenCashFlow is unconfigured. + +After startup: + +1. Open `http://localhost:5200`. +2. The WebApp redirects to `/Setup`. +3. Enter the company name, first administrator name, email, language, currency, country, and timezone. +4. OpenCashFlow creates the first company/tenant and administrator. +5. OpenCashFlow generates a temporary administrator password. +6. The password is shown exactly once. +7. Log in with the administrator email and generated password. +8. Change the password when prompted. + +The setup wizard configures application data only. It does not create PostgreSQL users, create databases, change database permissions, or provision infrastructure. + +## Stop The Stack + +Stop containers but keep the database volume: + +```bash +docker compose -f docker-compose.release.yml stop +``` + +Stop and remove containers while keeping the database volume: + +```bash +docker compose -f docker-compose.release.yml down +``` + +Do not run `docker compose down -v` unless you intentionally want to remove the PostgreSQL volume and lose local data. + +## Update The Stack + +For a newer preview tag: + +1. Read the release notes. +2. Back up the database. +3. Update `OPENCASHFLOW_VERSION` in `.env`, or use the new package with its default image tag. +4. Pull images and restart: + +```bash +docker compose -f docker-compose.release.yml pull +docker compose -f docker-compose.release.yml up -d +``` + +If `AUTO_MIGRATE=true`, the API applies pending migrations on startup. For important data, test the update on a copied database before updating the primary instance. + +## Backup + +Create a PostgreSQL custom-format backup: + +```bash +docker compose -f docker-compose.release.yml exec db \ + pg_dump -U "${POSTGRES_USER:-postgres}" \ + -d "${POSTGRES_DB:-opencashflow}" \ + -Fc \ + -f /tmp/opencashflow.backup + +docker compose -f docker-compose.release.yml cp \ + db:/tmp/opencashflow.backup ./opencashflow.backup +``` + +Store the backup somewhere outside the Compose project directory. + +## Restore + +Restore into a clean PostgreSQL database only after reviewing the backup/restore drill: + +```text +Docs/ops/backup-restore-drill.md +``` + +Do not overwrite a live database without a tested recovery plan. + +## Useful Checks + +Check container status: + +```bash +docker compose -f docker-compose.release.yml ps +``` + +Check logs: + +```bash +docker compose -f docker-compose.release.yml logs api +docker compose -f docker-compose.release.yml logs webapp +docker compose -f docker-compose.release.yml logs db +``` + +Check API health: + +```bash +curl -fsS http://localhost:5100/health +``` + +## Current Limitations + +- This is a Developer Preview / Early Self-Hosted Preview. +- The release Compose file is an evaluation path, not a complete production deployment. +- Cash Custody persistence is not complete yet. +- Backup/restore and upgrade procedures must be validated for your own environment. +- Secrets, TLS, monitoring, and operational runbooks are your responsibility before shared use. diff --git a/Docs/setup/docker-compose-visual-guide.md b/Docs/setup/docker-compose-visual-guide.md new file mode 100644 index 0000000..5979c06 --- /dev/null +++ b/Docs/setup/docker-compose-visual-guide.md @@ -0,0 +1,144 @@ +# Docker Compose Visual Guide + +This visual guide explains the OpenCashFlow preview release package for first-time Docker Compose users. + +OpenCashFlow is shipped as a three-service stack: + +- `db`: PostgreSQL database. +- `api`: OpenCashFlow API. +- `webapp`: browser-facing WebApp. + +The release package is for evaluation and early self-hosted testing. It is not a production-ready deployment profile. + +## 1. Understand The Stack + +![Docker Compose stack](../assets/setup/docker-compose-stack.svg) + +Docker Compose creates a private network for the containers. + +- `api` connects to PostgreSQL using the internal hostname `db`. +- `webapp` connects to the API using the internal hostname `api`. +- You open the WebApp from your browser at `http://localhost:5200`. +- The API health endpoint is available at `http://localhost:5100/health`. + +## 2. Download The Preview Package + +```bash +curl -LO https://github.com/Reckonry/OpenCashFlow/releases/download/v0.1.0-preview.2/OpenCashFlow-0.1.0-preview.2.tar.gz +# or: +# wget https://github.com/Reckonry/OpenCashFlow/releases/download/v0.1.0-preview.2/OpenCashFlow-0.1.0-preview.2.tar.gz +tar -xzf OpenCashFlow-0.1.0-preview.2.tar.gz +cd OpenCashFlow-0.1.0-preview.2 +``` + +## 3. Configure `.env` + +![Edit .env configuration](../assets/setup/env-configuration.svg) + +Create a local environment file: + +```bash +cp .env.example .env +``` + +Edit `.env` before shared use. + +At minimum, change: + +- `JWT_SECRET` +- `POSTGRES_PASSWORD` +- `APP_URL`, if users will open a URL other than `http://localhost:5200` + +SMTP can remain empty for the first local setup. + +## 4. Start The Stack + +```bash +docker compose -f docker-compose.release.yml up -d +``` + +Check status: + +```bash +docker compose -f docker-compose.release.yml ps +curl -fsS http://localhost:5100/health +``` + +## 5. Complete First-Run Setup + +![First-run setup wizard](../assets/setup/first-run-setup.svg) + +Open: + +```text +http://localhost:5200 +``` + +On a fresh database, the WebApp redirects to `/Setup`. + +Enter: + +- company name; +- administrator first and last name; +- administrator email; +- language; +- currency; +- country; +- timezone. + +The setup wizard creates application data only. It does not provision PostgreSQL users, databases, permissions, TLS, or infrastructure. + +## 6. Store The Temporary Password + +![Generated admin password shown once](../assets/setup/generated-password-once.svg) + +After setup completes, OpenCashFlow shows a generated temporary administrator password exactly once. + +Store it immediately. It is not shown again. + +Do not paste this password into issues, screenshots, logs, or support channels. + +## 7. First Login And Password Change + +![First login requires password change](../assets/setup/first-login-password-change.svg) + +Log in with: + +- administrator email; +- generated temporary password. + +OpenCashFlow requires a password change before normal use. + +## 8. Stop, Update, And Back Up + +Stop without deleting data: + +```bash +docker compose -f docker-compose.release.yml down +``` + +Update to a newer preview: + +```bash +docker compose -f docker-compose.release.yml pull +docker compose -f docker-compose.release.yml up -d +``` + +Back up PostgreSQL before updates: + +```bash +docker compose -f docker-compose.release.yml exec db \ + pg_dump -U "${POSTGRES_USER:-postgres}" \ + -d "${POSTGRES_DB:-opencashflow}" \ + -Fc \ + -f /tmp/opencashflow.backup + +docker compose -f docker-compose.release.yml cp \ + db:/tmp/opencashflow.backup ./opencashflow.backup +``` + +Read the full install guide for more detail: + +```text +Docs/setup/docker-compose-release-install.md +``` diff --git a/Docs/wiki/Docker-Compose-Install.md b/Docs/wiki/Docker-Compose-Install.md new file mode 100644 index 0000000..2f6ceb5 --- /dev/null +++ b/Docs/wiki/Docker-Compose-Install.md @@ -0,0 +1,53 @@ +# Docker Compose Install + +OpenCashFlow preview releases run as a Docker Compose stack with three services: + +- `db` +- `api` +- `webapp` + +## Minimal Install + +```bash +curl -LO https://github.com/Reckonry/OpenCashFlow/releases/download/v0.1.0-preview.2/OpenCashFlow-0.1.0-preview.2.tar.gz +tar -xzf OpenCashFlow-0.1.0-preview.2.tar.gz +cd OpenCashFlow-0.1.0-preview.2 +cp .env.example .env +docker compose -f docker-compose.release.yml up -d +``` + +Open: + +```text +http://localhost:5200 +``` + +On a fresh database, complete `/Setup`. + +## Important Configuration + +Edit `.env` before shared use: + +- change `JWT_SECRET`; +- change `POSTGRES_PASSWORD`; +- set `APP_URL` to the real WebApp URL; +- configure SMTP if email features are needed. + +## Visual Guide + +The source repository includes a visual guide: + +```text +Docs/setup/docker-compose-visual-guide.md +``` + +## Manual Wiki Publishing + +```bash +git clone https://github.com/Reckonry/OpenCashFlow.wiki.git +cp Docs/wiki/*.md OpenCashFlow.wiki/ +cd OpenCashFlow.wiki +git add . +git commit -m "Add Docker Compose install guide" +git push +``` diff --git a/Docs/wiki/Home.md b/Docs/wiki/Home.md new file mode 100644 index 0000000..a208377 --- /dev/null +++ b/Docs/wiki/Home.md @@ -0,0 +1,25 @@ +# OpenCashFlow Wiki + +OpenCashFlow is a Developer Preview / Early Self-Hosted Preview. + +Start here: + +- [Docker Compose Install](Docker-Compose-Install) +- [First-Run Setup Wizard](../setup/first-run-setup-wizard.md) +- [Production Hardening](../ops/production-hardening.md) +- [Backup And Restore Drill](../ops/backup-restore-drill.md) + +## Manual Wiki Publishing + +This repository keeps wiki source files under `Docs/wiki/`. They are prepared for manual publishing only. + +```bash +git clone https://github.com/Reckonry/OpenCashFlow.wiki.git +cp Docs/wiki/*.md OpenCashFlow.wiki/ +cd OpenCashFlow.wiki +git add . +git commit -m "Add Docker Compose install guide" +git push +``` + +Do not publish automatically from CI until the wiki workflow and permissions are explicitly reviewed. diff --git a/README.md b/README.md index 048a270..dfb2a7a 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,12 @@ The release Compose file uses published GHCR images instead of building from sou On a fresh database, open `http://localhost:5200` and complete the first-run setup wizard. +For a step-by-step explanation of the release stack, `.env`, startup, updates, backups, and first-run setup, see +[Docs/setup/docker-compose-release-install.md](Docs/setup/docker-compose-release-install.md). + +For a visual walkthrough of the Docker Compose release package, see +[Docs/setup/docker-compose-visual-guide.md](Docs/setup/docker-compose-visual-guide.md). + ### Run Manually Configure `DEFAULT_CONN_STRING` or `ConnectionStrings:DefaultConnectionString`, then run: