Installation
Get your self-hosted family planner running in a few minutes. No programming experience required — just Docker.
Before you start
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.
Packages the app so you don't need to install anything else. Free for personal use.
A command-line interface to type a few commands. Built into every OS — no extra install needed.
256 MB RAM minimum. Runs on a Raspberry Pi, NAS, home server, or any desktop machine.
Step by step
Open your terminal and clone Oikos to a folder of your choice.
Run this command from the repository root. The installer server starts on port 8090.
Navigate to the following address. The wizard will guide you through configuration, Docker startup, and admin account creation.
Open your terminal and run these two commands. They download the Docker configuration and the template for your settings.
Copy the template to create your own settings file. Then open .env in a text editor and set the two required secrets.
Generate a secure value for each secret by running this command twice — paste one result as SESSION_SECRET and one as DB_ENCRYPTION_KEY:
.env file somewhere safe. If you lose the DB_ENCRYPTION_KEY, your data cannot be recovered.
Docker will automatically download the Oikos image and start it in the background. The first download takes a minute.
You can verify it's running by checking the logs:
Server läuft auf Port 3000. Press Ctrl+C to stop following logs — the container keeps running.
Run the interactive setup wizard to create the first user account. You'll be asked for a username, display name, and password.
Copy the template to create your own settings file. Then open .env in a text editor and set the two required secrets.
Generate a secure value for each secret — run this twice:
The --build flag compiles the Docker image locally. This takes a few minutes the first time.
Run the interactive setup wizard to create the first user account. You'll be asked for a username, display name, and password.
Open your browser and navigate to:
Log in with the admin credentials you just created. You can add more family members from the Settings page.
Configuration
These two variables in your .env file are mandatory. Everything else is optional.
openssl rand -hex 32 to generate a secure value.openssl rand -hex 32. Back this up — without it, data is unrecoverable.Optional
Once Oikos is running, you can set up these extras. All are configured in your .env file.
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 →
Show the local weather on the dashboard. Set OPENWEATHER_API_KEY and OPENWEATHER_CITY — free API key from openweathermap.org.
Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV). Set the relevant GOOGLE_* or APPLE_* variables. Guide →
Add a daily cron job to back up your database. All data lives in the oikos_data Docker volume. Guide →
Pull the latest image and restart: docker compose pull && docker compose up -d. Your data persists across updates.
Troubleshooting
Most issues have a simple fix. Check below — if you're still stuck, open an issue on GitHub.
Another application is using port 3000. Either stop the conflicting process, or change the port in docker-compose.yml:
Or edit docker-compose.yml and change 3000:3000 to e.g. 8080:3000.
Add your user to the Docker group, then log out and back in:
Check the container status and logs:
Accessing from another device? Check your firewall rules.
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 deletes all data. Only use this on a fresh install with no data.
Nginx can't reach the container. Check that it's running and the port matches:
Ensure the proxy_pass port in your Nginx config matches the host port in docker-compose.yml (default: 3000).