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)
This commit is contained in:
Ulas
@@ -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
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"></a>
|
||||
<a href="https://github.com/ulsklyc/oikos/releases"><img src="https://img.shields.io/github/v/release/ulsklyc/oikos?style=flat-square&color=007AFF&label=release" alt="Latest Release"></a>
|
||||
<a href="https://www.docker.com"><img src="https://img.shields.io/badge/docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker"></a>
|
||||
<a href="https://github.com/ulsklyc/oikos/pkgs/container/oikos"><img src="https://img.shields.io/badge/ghcr.io-oikos-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker Image"></a>
|
||||
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
|
||||
<a href="https://github.com/ulsklyc/oikos/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome"></a>
|
||||
</div>
|
||||
@@ -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
|
||||
|
||||
|
||||
+12
-13
@@ -593,7 +593,7 @@
|
||||
<div class="feature-card reveal">
|
||||
<div class="feature-icon" aria-hidden="true">📋</div>
|
||||
<h3 data-i18n="feat_tasks_title">Task Management</h3>
|
||||
<p data-i18n="feat_tasks_desc">Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board view.</p>
|
||||
<p data-i18n="feat_tasks_desc">Shared tasks with deadlines, priorities, subtasks, recurring schedules, and a Kanban board with one-tap status buttons.</p>
|
||||
</div>
|
||||
<div class="feature-card reveal reveal-delay-1">
|
||||
<div class="feature-icon" aria-hidden="true">🛒</div>
|
||||
@@ -613,7 +613,7 @@
|
||||
<div class="feature-card reveal">
|
||||
<div class="feature-icon" aria-hidden="true">💰</div>
|
||||
<h3 data-i18n="feat_budget_title">Budget Tracking</h3>
|
||||
<p data-i18n="feat_budget_desc">Track income and expenses, manage recurring entries, view monthly trends, and export to CSV.</p>
|
||||
<p data-i18n="feat_budget_desc">Track income and expenses, configurable currency (13 options), recurring entries, monthly trends, and CSV export.</p>
|
||||
</div>
|
||||
<div class="feature-card reveal reveal-delay-1">
|
||||
<div class="feature-icon" aria-hidden="true">📌</div>
|
||||
@@ -737,12 +737,11 @@
|
||||
</div>
|
||||
<div class="setup-content reveal">
|
||||
<div class="code-block" role="region" aria-label="Setup commands">
|
||||
<span class="comment"># Clone and configure</span>
|
||||
git clone https://github.com/ulsklyc/oikos.git && cd oikos
|
||||
<span class="comment"># Option A — pre-built image (no clone required)</span>
|
||||
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 <span class="comment"># set SESSION_SECRET and DB_ENCRYPTION_KEY</span>
|
||||
|
||||
<span class="comment"># Start with Docker</span>
|
||||
<span class="cmd">docker compose up -d --build</span>
|
||||
<span class="cmd">docker compose up -d</span>
|
||||
<span class="cmd">docker compose exec oikos node setup.js</span>
|
||||
</div>
|
||||
<p class="setup-note" data-i18n="setup_note">Then open <code>http://localhost:3000</code> and log in. Need help? The <a href="https://github.com/ulsklyc/oikos/blob/main/docs/installation.md" target="_blank" rel="noopener">Installation Guide</a> covers everything from installing Docker to HTTPS, backups, and troubleshooting.</p>
|
||||
@@ -779,7 +778,7 @@ cp .env.example .env <span class="comment"># 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 <span class="comment"># 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 <span class="comment"># 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 <code>http://localhost:3000</code> and log in. Need help? The <a href="https://github.com/ulsklyc/oikos/blob/main/docs/installation.md" target="_blank" rel="noopener">Installation Guide</a> covers everything from installing Docker to HTTPS, backups, and troubleshooting.',
|
||||
setup_note: 'Then open <code>http://localhost:3000</code> and log in. Want to build from source or set up HTTPS? The <a href="https://github.com/ulsklyc/oikos/blob/main/docs/installation.md" target="_blank" rel="noopener">Installation Guide</a> 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 <span class="comment"># 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 <span class="comment"># 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 <span class="comment"># 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 <code>http://localhost:3000</code> \u00f6ffnen und einloggen. Hilfe n\u00f6tig? Die <a href="https://github.com/ulsklyc/oikos/blob/main/docs/installation.md" target="_blank" rel="noopener">Installationsanleitung</a> erkl\u00e4rt alles \u2014 von Docker-Installation bis HTTPS, Backups und Fehlersuche.',
|
||||
setup_note: 'Dann <code>http://localhost:3000</code> \u00f6ffnen und einloggen. Build aus dem Quellcode oder HTTPS einrichten? Die <a href="https://github.com/ulsklyc/oikos/blob/main/docs/installation.md" target="_blank" rel="noopener">Installationsanleitung</a> erkl\u00e4rt alle Optionen.',
|
||||
footer_heart: 'Mit Sorgfalt gebaut f\u00fcr Familien, die Privatsph\u00e4re und Einfachheit sch\u00e4tzen.',
|
||||
footer_contrib: 'Mitmachen'
|
||||
}
|
||||
|
||||
+76
-27
@@ -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=<YOUR-SECRET>
|
||||
DB_ENCRYPTION_KEY=<YOUR-SECRET>
|
||||
```
|
||||
|
||||
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=<YOUR-SECRET>
|
||||
DB_ENCRYPTION_KEY=<YOUR-SECRET>
|
||||
```
|
||||
|
||||
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 <a name="4-verify-the-container-is-running"></a>
|
||||
|
||||
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
|
||||
<details>
|
||||
<summary>SQLCipher build fails during Docker build</summary>
|
||||
|
||||
> **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.
|
||||
|
||||
+1
-1
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user