From cde511da1d73ccc3edafcbf070746845c5a9bf99 Mon Sep 17 00:00:00 2001 From: Ulas Date: Sun, 5 Apr 2026 16:29:12 +0200 Subject: [PATCH] docs: update README, installation guide and GitHub Pages - README: GHCR badge, Kanban quick-status buttons and configurable currency mentioned in highlights - installation.md: Option A (pre-built image, no clone) as primary path, Option B (build from source) as alternative; Updates section updated; SQLCipher troubleshooting tip added - index.html: Get Started block now shows pre-built image path; task and budget feature cards updated (EN + DE translations) --- CHANGELOG.md | 7 +++ README.md | 6 +-- docs/index.html | 25 +++++------ docs/installation.md | 103 +++++++++++++++++++++++++++++++------------ package.json | 2 +- 5 files changed, 99 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 00e90ca..70d2bb9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.11.9] - 2026-04-05 + +### Changed +- README: updated highlights to mention Kanban quick-status buttons and configurable budget currency; replaced docker badge with GHCR link +- docs/installation.md: restructured setup into Option A (pre-built GHCR image, no clone needed) and Option B (build from source); updated Updates section accordingly; added tip to SQLCipher troubleshooting entry +- docs/index.html (GitHub Pages): updated Get Started code block to show pre-built image path; updated task and budget feature descriptions (EN + DE) to reflect new features + ## [0.11.8] - 2026-04-05 ### Changed diff --git a/README.md b/README.md index 42ffa14..6f2f716 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ MIT License Latest Release - Docker + Docker Image Node.js PRs Welcome @@ -43,7 +43,7 @@ ## Highlights -**Task Management:** Shared tasks with deadlines, priorities, subtasks, recurring schedules, and Kanban view +**Task Management:** Shared tasks with deadlines, priorities, subtasks, recurring schedules, Kanban view with one-tap status buttons for touch devices **Shopping Lists:** Collaborative lists with aisle categories and one-click import from meal plans @@ -51,7 +51,7 @@ **Calendar Sync:** Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV) -**Budget Tracking:** Income and expenses, recurring entries, monthly trends, CSV export +**Budget Tracking:** Income and expenses, recurring entries, configurable currency (13 currencies), monthly trends, CSV export **Notes & Contacts:** Colored sticky notes with Markdown, contact directory with vCard import/export diff --git a/docs/index.html b/docs/index.html index 9cd9484..8c019ba 100644 --- a/docs/index.html +++ b/docs/index.html @@ -593,7 +593,7 @@

Task Management

-

Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board view.

+

Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board with one-tap status buttons.

@@ -613,7 +613,7 @@

Budget Tracking

-

Track income and expenses, manage recurring entries, view monthly trends, and export to CSV.

+

Track income and expenses, configurable currency (13 options), recurring entries, monthly trends, and CSV export.

@@ -737,12 +737,11 @@
-# Clone and configure -git clone https://github.com/ulsklyc/oikos.git && cd oikos +# Option A — pre-built image (no clone required) +curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml +curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/.env.example cp .env.example .env # set SESSION_SECRET and DB_ENCRYPTION_KEY - -# Start with Docker -docker compose up -d --build +docker compose up -d docker compose exec oikos node setup.js

Then open http://localhost:3000 and log in. Need help? The Installation Guide covers everything from installing Docker to HTTPS, backups, and troubleshooting.

@@ -779,7 +778,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY features_title: 'Everything your household needs', features_desc: 'A complete set of tools designed for families, built to work together seamlessly.', feat_tasks_title: 'Task Management', - feat_tasks_desc: 'Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board view.', + feat_tasks_desc: 'Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board with one-tap status buttons.', feat_shopping_title: 'Shopping Lists', feat_shopping_desc: 'Collaborative lists with aisle categories and one-click import from your meal plans.', feat_meals_title: 'Meal Planning', @@ -787,7 +786,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY feat_calendar_title: 'Calendar Sync', feat_calendar_desc: 'Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV). All events in one place.', feat_budget_title: 'Budget Tracking', - feat_budget_desc: 'Track income and expenses, manage recurring entries, view monthly trends, and export to CSV.', + feat_budget_desc: 'Track income and expenses, configurable currency (13 options), recurring entries, monthly trends, and CSV export.', feat_notes_title: 'Notes', feat_notes_desc: 'Colored sticky notes with Markdown support. Perfect for family memos, recipes, and quick reminders.', feat_contacts_title: 'Contacts', @@ -810,7 +809,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY phil_open_desc: 'MIT licensed. Inspect, modify, extend, contribute. Built in the open for families who care about transparency.', setup_label: 'Get Started', setup_title: 'Up and running in minutes', - setup_note: 'Then open http://localhost:3000 and log in. Need help? The Installation Guide covers everything from installing Docker to HTTPS, backups, and troubleshooting.', + setup_note: 'Then open http://localhost:3000 and log in. Want to build from source or set up HTTPS? The Installation Guide covers all options.', footer_heart: 'Built with care for families who value privacy and simplicity.', footer_contrib: 'Contributing' }, @@ -825,7 +824,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY features_title: 'Alles, was euer Haushalt braucht', features_desc: 'Ein vollst\u00e4ndiges Werkzeugset f\u00fcr Familien \u2014 nahtlos aufeinander abgestimmt.', feat_tasks_title: 'Aufgabenverwaltung', - feat_tasks_desc: 'Gemeinsame Aufgaben mit Fristen, Priorit\u00e4ten, Unteraufgaben, wiederkehrenden Terminen und Kanban-Ansicht.', + feat_tasks_desc: 'Gemeinsame Aufgaben mit Fristen, Priorit\u00e4ten, Unteraufgaben, wiederkehrenden Terminen und Kanban-Board mit Ein-Tipp-Status-Buttons.', feat_shopping_title: 'Einkaufslisten', feat_shopping_desc: 'Gemeinsame Listen mit Gang-Kategorien und Ein-Klick-Import aus Mahlzeitenpl\u00e4nen.', feat_meals_title: 'Mahlzeitenplanung', @@ -833,7 +832,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY feat_calendar_title: 'Kalender-Sync', feat_calendar_desc: 'Zwei-Wege-Sync mit Google Calendar (OAuth) und Apple iCloud (CalDAV). Alle Termine an einem Ort.', feat_budget_title: 'Budgetverwaltung', - feat_budget_desc: 'Einnahmen und Ausgaben verfolgen, wiederkehrende Eintr\u00e4ge verwalten, monatliche Trends und CSV-Export.', + feat_budget_desc: 'Einnahmen und Ausgaben verfolgen, konfigurierbare W\u00e4hrung (13 Optionen), wiederkehrende Eintr\u00e4ge, monatliche Trends und CSV-Export.', feat_notes_title: 'Notizen', feat_notes_desc: 'Farbige Haftnotizen mit Markdown. Perfekt f\u00fcr Familien-Memos, Rezepte und schnelle Erinnerungen.', feat_contacts_title: 'Kontakte', @@ -856,7 +855,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY phil_open_desc: 'MIT-lizenziert. Einsehen, anpassen, erweitern, beitragen. Offen gebaut f\u00fcr Familien, die Transparenz sch\u00e4tzen.', setup_label: 'Loslegen', setup_title: 'In Minuten einsatzbereit', - setup_note: 'Dann http://localhost:3000 \u00f6ffnen und einloggen. Hilfe n\u00f6tig? Die Installationsanleitung erkl\u00e4rt alles \u2014 von Docker-Installation bis HTTPS, Backups und Fehlersuche.', + setup_note: 'Dann http://localhost:3000 \u00f6ffnen und einloggen. Build aus dem Quellcode oder HTTPS einrichten? Die Installationsanleitung erkl\u00e4rt alle Optionen.', footer_heart: 'Mit Sorgfalt gebaut f\u00fcr Familien, die Privatsph\u00e4re und Einfachheit sch\u00e4tzen.', footer_contrib: 'Mitmachen' } diff --git a/docs/installation.md b/docs/installation.md index 691d4a0..0501fea 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -69,51 +69,83 @@ git --version # git version 2.x.x ## Step-by-Step Installation -### 1. Clone the Repository +There are two ways to get Oikos running. **Option A** (pre-built image) is recommended for most users — no clone required. **Option B** (build from source) is for contributors or if you want to run a custom version. -Download the Oikos source code to your machine: +--- + +### Option A — Pre-built Image (Recommended) + +A ready-to-use Docker image is published to the GitHub Container Registry on every release. You only need two files. + +#### 1. Download the Compose File and Example Config + +```bash +curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml +curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/.env.example +``` + +#### 2. Configure Environment Variables + +```bash +cp .env.example .env +``` + +Open `.env` and set at minimum the two required secrets: + +```bash +SESSION_SECRET= +DB_ENCRYPTION_KEY= +``` + +Generate a secure value for each: + +```bash +openssl rand -hex 32 +``` + +Run this command **twice** and paste each result. See [Environment Variables](#environment-variables) for all options. + +#### 3. Start the Container + +```bash +docker compose up -d +``` + +Docker pulls `ghcr.io/ulsklyc/oikos:latest` automatically. No build step, no Node.js installation needed. + +Continue with [Step 4 — Verify](#4-verify-the-container-is-running). + +--- + +### Option B — Build from Source + +#### 1. Clone the Repository ```bash git clone https://github.com/ulsklyc/oikos.git cd oikos ``` -### 2. Configure Environment Variables - -Copy the example environment file and edit it with your own values: +#### 2. Configure Environment Variables ```bash cp .env.example .env ``` -Open `.env` in a text editor and change at least the two secret values - see the [Environment Variables](#environment-variables) section for full details. The critical ones: +Open `.env` and set the two required secrets (see above). Generate them with `openssl rand -hex 32`. -```bash -# Generate secure values for these: -SESSION_SECRET= -DB_ENCRYPTION_KEY= -``` - -Generate a secure random string: - -```bash -openssl rand -hex 32 -``` - -Run this command **twice** - once for `SESSION_SECRET` and once for `DB_ENCRYPTION_KEY`. Paste each result into your `.env` file. - -### 3. Build and Start the Container +#### 3. Build and Start the Container ```bash docker compose up -d --build ``` -- `--build` builds the Docker image from the Dockerfile (compiles SQLCipher dependencies, installs npm packages). -- `-d` runs the container in the background (detached mode). +- `--build` compiles the Docker image locally (SQLCipher dependencies, npm packages). +- `-d` runs the container in the background. The first build takes a few minutes. Subsequent starts are much faster. -### 4. Verify the Container is Running +### 4. Verify the Container is Running Check the logs to confirm a successful start: @@ -305,7 +337,18 @@ docker compose up -d ## Updates -### Standard Update +### Option A — Pre-built Image + +Pull the latest published image and restart: + +```bash +docker compose pull +docker compose up -d +``` + +No rebuild needed. The database volume persists across updates. + +### Option B — Build from Source ```bash cd oikos @@ -313,13 +356,17 @@ git pull docker compose up -d --build ``` -This pulls the latest code, rebuilds the image with any new dependencies, and restarts the container. The database volume persists across rebuilds. - ### When to Stop First If the [CHANGELOG](../CHANGELOG.md) mentions database migrations or breaking changes, stop the container before updating: ```bash +# Option A (pre-built) +docker compose pull +docker compose down +docker compose up -d + +# Option B (build from source) docker compose down git pull docker compose up -d --build @@ -447,6 +494,8 @@ If you have existing data, you need the original encryption key. There is no way
SQLCipher build fails during Docker build +> **Tip**: If you hit build issues, switch to the pre-built image (Option A above) — it ships with SQLCipher already compiled and requires no local build step. + The Dockerfile installs these build dependencies: `python3`, `make`, `g++`, `libsqlcipher-dev`. If the build fails, ensure your Docker installation is up to date and has internet access to pull packages. On resource-constrained systems, the native compilation may run out of memory. Ensure at least 1 GB of RAM is available during the build. diff --git a/package.json b/package.json index 0ea55a1..96e828d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "oikos", - "version": "0.11.8", + "version": "0.11.9", "description": "Self-hosted family planner - calendar, tasks, shopping, meal planning, budget and more. Private, open-source, no subscription.", "main": "server/index.js", "type": "module",