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. A browser-based wizard configures your .env, starts Docker, and creates your admin account — no manual steps. Requires Node.js 18+ on the host.
1

### Clone the repository

Open your terminal and clone Oikos to a folder of your choice.

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

### Start the installer

Run this command from the repository root. The installer server starts on port 8090.

node tools/installer/install-server.js
3

### Open the wizard in your browser

Navigate to the following address. The wizard will guide you through configuration, Docker startup, and admin account creation.

http://localhost:8090
The installer shuts down automatically after setup completes. Your Oikos instance keeps running via Docker.
No Git, no build step — just two files and a single command. Requires only Docker.
1

### 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
2

### 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.
3

### 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.
4

### 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.
1

### Clone the repository

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

### 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
3

### Build and start

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

docker compose up -d --build
4

### 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).