simple-home

A minimal personal start page: clock, calendar, multi-provider web search, and bookmark management - all from a single browser homepage.

One URL for your searches and bookmarks. Self-hosted, no sync required. This tool is targeting people that do a lot of browser-hopping, or want their bookmarks and search providers on their server instead of in their browser.

Light	Dark

---

Warning

simple-home has no built-in authentication. It is designed to run exclusively behind a reverse proxy with an authentication layer (e.g. Traefik + Authentik ForwardAuth, or Authelia). Exposing this app directly to the internet gives anyone full read and write access to your bookmarks and configuration.

---

Features

• Multi-provider search with shortcodes (e.g. /g for Google, /yt for YouTube)
• Bookmark management: add, edit, delete, tag, and search directly from the UI
• Opinionated UI: A calendar, a date, the hour and a searchbar.
• Background images: random pick per page load from a mounted folder, CSS gradient fallback
• Light/dark theme following system preference
• rootless/distroless image: Minimal footprint (~5mb RAM usage, ~15mb docker image), no shell available.

Deploy

The deploy/example/ directory contains a ready-to-use Compose setup. Copy it somewhere on your host and adjust to taste.

1. Copy the example directory

cp -r deploy/example /wherever/you/host/simple-home
cd /wherever/you/host/simple-home

The directory layout after copying:

simple-home/
├── backgrounds/
│   ├── dark/             # dark-theme background images (optional)
│   └── light/            # light-theme background images (optional)
├── data/
│   ├── config.yaml
│   └── bookmarks.json    # Has to exist before starting the container with minimal content.
└── compose.yaml

2. Edit config.yaml

Open data/config.yaml and adjust to your needs. See Configuration below for all available fields.

3. Start the container

docker compose up -d

The app listens on 127.0.0.1:8080 by default. Wire your reverse proxy to that address and protect it with your auth layer before exposing it externally.

Updating

docker compose pull && docker compose up -d

Configuration

data/config.yaml

Field	Description	Example
default_provider	Shortcode of the default search provider	ddg
bookmarks_shortcode	Shortcode to enter bookmark search mode	bm
week_start	First day of the week in the calendar	monday or sunday
date_format	Go time format string for the date display	Monday, January 2 2006, 2006-01-02, ...
providers[].name	Display name of the search provider	DuckDuckGo
providers[].shortcode	Short code to activate this provider	ddg
providers[].url	Search URL with {query} placeholder	https://duckduckgo.com/?q={query}

Changes take effect on container restart.

Volumes

Host path	Container path	Notes
./data/config.yaml	/data/config.yaml	Read-only. App configuration.
./data/bookmarks.json	/data/bookmarks.json	Read-write. Edited via the UI. File has to exist before starting the container. Minimal content = [].
./backgrounds/	/backgrounds/	Read-only. Optional background images.

Environment variables

Variable	Default	Description
CONFIG_PATH	data/config.yaml	Path to the config file inside the container
BOOKMARKS_PATH	data/bookmarks.json	Path to the bookmarks file inside the container
BACKGROUNDS_PATH	(unset)	Path to background images folder. Leave unset to disable.
ADDR	:8080	Listen address

Background images

Drop any image files into backgrounds/dark/ or backgrounds/light/. One is picked at random on each page load based on the active theme. If the folder is absent or empty, a CSS gradient is used instead.

Development

See resources/README.md for local development setup, file structure, and API reference.

Dependencies

• standard go libraries
• gopkg.in/yaml.v3

AI disclosure

This tool has been written with Claude Code Sonnet 4.6. Reviewed and tested by a human.