From 592287ea4ee2a67404d123340365f34e31ea1daa Mon Sep 17 00:00:00 2001 From: Ulas Kalayci Date: Sun, 19 Apr 2026 17:17:10 +0200 Subject: [PATCH] docs: add installation guide page for GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/install.html โ€” a visually polished, bilingual (EN/DE) installation guide matching the index.html design system. Features step-by-step layout with numbered steps, copy buttons, tabbed Option A/B install paths, troubleshooting accordion, and dark mode support. Updates docs/index.html with a secondary "Installation Guide" CTA in the hero section and updated setup-note link pointing to the new page instead of the raw GitHub markdown file. Co-Authored-By: Claude Sonnet 4.6 --- docs/index.html | 20 +- docs/install.html | 1179 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1193 insertions(+), 6 deletions(-) mode change 100644 => 100755 docs/index.html create mode 100644 docs/install.html diff --git a/docs/index.html b/docs/index.html old mode 100644 new mode 100755 index 8c019ba..5bea2a7 --- a/docs/index.html +++ b/docs/index.html @@ -569,10 +569,16 @@

Oikos

The self-hosted family planner

Manage your household together. Tasks, shopping, meals, calendar, budget - all in one place. Self-hosted, private, yours.

- - - View on GitHub - +
+ + + View on GitHub + + + + Installation Guide + +
MIT License Docker Ready @@ -773,6 +779,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY hero_tagline: 'The self-hosted family planner', hero_desc: 'Manage your household together. Tasks, shopping, meals, calendar, budget \u2014 all in one place. Self-hosted, private, yours.', hero_cta: 'View on GitHub', + hero_install: 'Installation Guide', badge_nocloud: 'No Cloud Required', features_label: 'Features', features_title: 'Everything your household needs', @@ -809,7 +816,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. Want to build from source or set up HTTPS? The Installation Guide covers all options.', + setup_note: 'Then open http://localhost:3000 and log in. Want a step-by-step guide, HTTPS setup, or troubleshooting? See the Installation Guide.', footer_heart: 'Built with care for families who value privacy and simplicity.', footer_contrib: 'Contributing' }, @@ -819,6 +826,7 @@ cp .env.example .env # set SESSION_SECRET and DB_ENCRY hero_tagline: 'Der selbstgehostete Familienplaner', hero_desc: 'Organisiert euren Haushalt gemeinsam. Aufgaben, Einkauf, Mahlzeiten, Kalender, Budget \u2014 alles an einem Ort. Selbstgehostet, privat, eures.', hero_cta: 'Auf GitHub ansehen', + hero_install: 'Installationsanleitung', badge_nocloud: 'Keine Cloud n\u00f6tig', features_label: 'Funktionen', features_title: 'Alles, was euer Haushalt braucht', @@ -855,7 +863,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. Build aus dem Quellcode oder HTTPS einrichten? Die Installationsanleitung erkl\u00e4rt alle Optionen.', + setup_note: 'Dann http://localhost:3000 \u00f6ffnen und einloggen. Schritt-f\u00fcr-Schritt-Anleitung, HTTPS oder Hilfe bei Problemen? Zur Installationsanleitung.', footer_heart: 'Mit Sorgfalt gebaut f\u00fcr Familien, die Privatsph\u00e4re und Einfachheit sch\u00e4tzen.', footer_contrib: 'Mitmachen' } diff --git a/docs/install.html b/docs/install.html new file mode 100644 index 0000000..b2cfe83 --- /dev/null +++ b/docs/install.html @@ -0,0 +1,1179 @@ + + + + + + Install Oikos โ€” Self-Hosted Family Planner + + + + + + + + + + + + + + + + +
+
+

+ + Installation +

+

Install Oikos

+

Get your self-hosted family planner running in a few minutes. No programming experience required โ€” just Docker.

+
+ + + ~10 minutes + +
+
+
+ + +
+
+

Before you start

+

What you need

+

Oikos runs as a Docker container โ€” you don't need to install Node.js or any other runtime. Just Docker, and you're good to go.

+
+
+ +

Docker

+

Packages the app so you don't need to install anything else. Free for personal use.

+
+ macOS + Windows + Linux +
+
+
+ +

Terminal

+

A command-line interface to type a few commands. Built into every OS โ€” no extra install needed.

+
+ macOS: Terminal ยท Windows: PowerShell ยท Linux: bash +
+
+
+ +

System

+

256 MB RAM minimum. Runs on a Raspberry Pi, NAS, home server, or any desktop machine.

+
+ ~500 MB disk for Docker image +
+
+
+
+
+ + +
+
+

Step by step

+

Installation

+ +
+ + +
+ + +
+
+ + Recommended for most users. No Git, no build step โ€” just two files and a single command. +
+ +
+ +
+

Download the configuration files

+

Open your terminal and run these two commands. They download the Docker configuration and the template for your settings.

+
+
curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml +curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/.env.example
+ +
+
+
+ +
+ +
+

Create your configuration

+

Copy the template to create your own settings file. Then open .env in a text editor and set the two required secrets.

+
+
cp .env.example .env
+ +
+

Generate a secure value for each secret by running this command twice โ€” paste one result as SESSION_SECRET and one as DB_ENCRYPTION_KEY:

+
+
openssl rand -hex 32
+ +
+
+ + Keep a backup of your .env file somewhere safe. If you lose the DB_ENCRYPTION_KEY, your data cannot be recovered. +
+
+
+ +
+ +
+

Start the container

+

Docker will automatically download the Oikos image and start it in the background. The first download takes a minute.

+
+
docker compose up -d
+ +
+

You can verify it's running by checking the logs:

+
+
docker compose logs -f
+ +
+
+ + You should see: Server lรคuft auf Port 3000. Press Ctrl+C to stop following logs โ€” the container keeps running. +
+
+
+ +
+ +
+

Create your admin account

+

Run the interactive setup wizard to create the first user account. You'll be asked for a username, display name, and password.

+
+
docker compose exec oikos node setup.js
+ +
+
+
+
+ + +
+
+ + For contributors or those who want to run a custom version. Requires Git. The first build takes a few minutes. +
+ +
+ +
+

Clone the repository

+
+
git clone https://github.com/ulsklyc/oikos.git +cd oikos
+ +
+
+
+ +
+ +
+

Create your configuration

+

Copy the template to create your own settings file. Then open .env in a text editor and set the two required secrets.

+
+
cp .env.example .env
+ +
+

Generate a secure value for each secret โ€” run this twice:

+
+
openssl rand -hex 32
+ +
+
+
+ +
+ +
+

Build and start

+

The --build flag compiles the Docker image locally. This takes a few minutes the first time.

+
+
docker compose up -d --build
+ +
+
+
+ +
+ +
+

Create your admin account

+

Run the interactive setup wizard to create the first user account. You'll be asked for a username, display name, and password.

+
+
docker compose exec oikos node setup.js
+ +
+
+
+
+
+
+ + +
+
+
+ +

You're all set!

+

Open your browser and navigate to:

+
http://localhost:3000
+

Log in with the admin credentials you just created. You can add more family members from the Settings page.

+
+ + + GitHub + + Full Technical Guide +
+
+
+
+ + +
+
+

Configuration

+

Required settings

+

These two variables in your .env file are mandatory. Everything else is optional.

+
+
+
SESSION_SECRET
+
Session Secret Required
+
Signs and verifies login cookies. Use openssl rand -hex 32 to generate a secure value.
+
+
+
DB_ENCRYPTION_KEY
+
Database Key Required
+
Encrypts your entire database with AES-256. Generate with openssl rand -hex 32. Back this up โ€” without it, data is unrecoverable.
+
+
+
+
+ + +
+
+

Optional

+

Go further

+

Once Oikos is running, you can set up these extras. All are configured in your .env file.

+
+
+

HTTPS & Network Access

+

Want to reach Oikos from other devices or the internet? Set up Nginx as a reverse proxy with a free Let's Encrypt SSL certificate. Guide โ†’

+
+
+

Weather Widget

+

Show the local weather on the dashboard. Set OPENWEATHER_API_KEY and OPENWEATHER_CITY โ€” free API key from openweathermap.org.

+
+
+

Calendar Sync

+

Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV). Set the relevant GOOGLE_* or APPLE_* variables. Guide โ†’

+
+
+

Automated Backups

+

Add a daily cron job to back up your database. All data lives in the oikos_data Docker volume. Guide โ†’

+
+
+

Updates

+

Pull the latest image and restart: docker compose pull && docker compose up -d. Your data persists across updates.

+
+
+
+
+ + +
+
+

Troubleshooting

+

Something not working?

+

Most issues have a simple fix. Check below โ€” if you're still stuck, open an issue on GitHub.

+
+
+ Port 3000 is already in use +
+

Another application is using port 3000. Either stop the conflicting process, or change the port in docker-compose.yml:

+
+
lsof -i :3000 # find what's using the port
+
+

Or edit docker-compose.yml and change 3000:3000 to e.g. 8080:3000.

+
+
+
+ Docker: Permission denied +
+

Add your user to the Docker group, then log out and back in:

+
+
sudo usermod -aG docker $USER
+
+
+
+
+ Container starts but the page is not reachable +
+

Check the container status and logs:

+
+
docker compose ps # should show "Up" and "healthy" +docker compose logs # look for error messages +docker port oikos # verify port mapping
+
+

Accessing from another device? Check your firewall rules.

+
+
+
+ Database encryption error +
+

The DB_ENCRYPTION_KEY in your .env is missing or doesn't match the key used when the database was created. If this is a fresh install, you can reset:

+
+
docker compose down -v +docker compose up -d
+
+
+ + docker compose down -v deletes all data. Only use this on a fresh install with no data. +
+
+
+
+ Nginx shows 502 Bad Gateway +
+

Nginx can't reach the container. Check that it's running and the port matches:

+
+
docker compose ps +docker compose logs | grep "Server lรคuft"
+
+

Ensure the proxy_pass port in your Nginx config matches the host port in docker-compose.yml (default: 3000).

+
+
+
+
+
+ + + + + +