StartPage Administrator Guide

Table of Contents

1. Overview
2. Embed Mode & Themes
3. Deployment Options
4. Docker Deployment
5. Local Development
6. Database Management
7. Database Migration Guide
8. Backup and Restore
9. Key Application Routes
10. Configuration
11. Troubleshooting

Overview

StartPage is a self-hosted, frecency-based link manager designed to serve as your browser start page. Links are dynamically ranked using a weighted algorithm that combines frequency and recency of access.

Key Features

• Frecency-based ranking - Links automatically prioritize based on usage patterns
• Tag system - Organize links with custom tags (personal, work, projects, etc.)
• Embed mode - Clean widget view for browser extensions and iframe integrations
• Theme controls - Force light or dark mode via URL parameters
• Automatic pruning - Links with rank below 1 are automatically removed
• Temporary links - Flag short-lived bookmarks that expire automatically (default 24 hours)
• Prometheus metrics - Scrape runtime and database gauges from /metrics
• SQLite storage - No external database required
• FastAPI backend - High performance Python web framework
• HTMX frontend - Dynamic updates without page reloads

Feature highlights

Embed Mode & Themes

StartPage supports URL parameters for creating embeddable widgets and forcing specific themes. These features are perfect for browser extensions, iframe integrations, or custom start page setups.

Embed Mode

Add ?embed=true to any URL to enable embed mode. This hides the navigation bar and footer, creating a minimal widget view.

http://localhost:8080/?embed=true
http://localhost:8080/?embed=true&tag=work
http://localhost:8080/dashboard?embed=true

Theme Parameter

Force a specific theme using the ?theme parameter. Available options:

• ?theme=dark - Force dark mode (Catppuccin Mocha)
• ?theme=light - Force light mode (Catppuccin Latte)
• No parameter - Use system preference (default behavior)

http://localhost:8080/?theme=dark
http://localhost:8080/?theme=light

Combining Parameters

You can use both embed mode and theme parameters together. All navigation within embed mode (tag filters, search, pagination) automatically preserves these parameters.

http://localhost:8080/?embed=true&theme=dark
http://localhost:8080/?embed=true&theme=light&tag=personal

Use Cases

Implementation Details

The embed mode and theme parameters are:

• Stateless - No cookies or local storage required
• Persistent - Parameters are preserved across all navigation (tag filters, pagination, search)
• Automatic - Template context helper embed_query_params handles parameter propagation
• Flexible - Works on all routes including index, dashboard, tags, and search results

Deployment Options

Docker Deployment

Quick Start

just dockerbuild

This command builds the container and runs it with persistent storage at ~/.config/startpage

Manual Docker Commands

Build the Docker image:

docker build . -t startpage

Run the container:

docker run -d -p 8080:8080 \
  --restart=always \
  --name startpage \
  -v ~/.config/startpage:/usr/startpage/data \
  startpage

Docker Configuration

Environment variables you can set:

• WORKERS - Number of Uvicorn workers (default: 2)
• LOG_LEVEL - Logging level (default: info)

Accessing the Application

Once running, access StartPage at: http://localhost:8080

Docker Management

# Stop the container
docker stop startpage

# Start the container
docker start startpage

# View logs
docker logs startpage

# Restart the container
docker restart startpage
# or via justfile shortcut
just restart

# Remove the container
docker rm -f startpage

Updating the Container (just docker-replace)

To pull the latest code and replace the running container in one step:

just docker-replace

This recipe runs git pull, rebuilds the image, stops and removes the old container, and starts the new one with the same volume mount. Equivalent to running the stop/rm/build/run sequence manually.

Local Development

Prerequisites

• Python 3.10 or higher
• uv package manager
• just command runner (for justfile recipes)

Install just using your platform package manager: just.systems/man/en/packages.html

Installation

# Install dependencies
uv sync
# or
just install

Running Locally

Development mode (with hot reload):

just develop
# or with a custom port (default is 8000, not the Docker port 8080)
just develop 8080
# or directly
uv run uvicorn main:app --reload

Production mode (in screen session):

just run

This runs the app in a detached screen session named startpage. Use screen -r startpage to attach.

Standard run:

uv run uvicorn main:app

Testing

# Run all tests
uv run pytest

# Run specific test module
uv run pytest services/test_db_utils.py

# Type checking
uv run mypy services

Database Management

Database Location

• Local: data/links.db
• Docker: ~/.config/startpage/links.db (mounted from host)

For the full schema including an ER diagram and column descriptions, see dbschema.md in the project root.

Direct SQL maintenance

For bulk edits or scripted maintenance you can work directly against the SQLite database.

1. Connect with sqlite3.

   sqlite3 data/links.db
   .headers on
   .mode column
   SELECT id, name, rank FROM links ORDER BY rank DESC LIMIT 5;
   UPDATE links SET rank = 1.0 WHERE name = 'Docs';
   .quit

2. Understand the schema. Core tables are links (primary data), tags, and tagmap. Foreign keys keep orphaned rows from lingering, so deleting a tag automatically clears tagmap entries.
3. Automate with Python. Import services.db_utils in your own scripts to re-use helpers such as save_link, get_links, rename_tag, or delete_link.

Remember: treat data/links.db as disposable state—commit schema changes and SQL scripts, not the database file.

Schema Versions

Checking Database Version

sqlite3 data/links.db "SELECT value FROM metadata WHERE name = 'db_version';"

Database Migration Guide

Automatic Migration

StartPage automatically migrates your database when you upgrade to a new major version. The migration happens on the first application start after upgrading.

How it works:

1. Application starts and reads the current database version from metadata table
2. Compares with the app version from pyproject.toml
3. If major versions differ, runs the appropriate migration script from sql_scripts/
4. Updates the db_version in the metadata table

Migration from v1 to v2

Version 2 adds the tagging feature. The migration adds two new tables:

• tags - Stores tag definitions
• tagmap - Maps tags to links (many-to-many relationship)

Steps to migrate:

# 1. Backup your database
cp data/links.db data/links.db.backup

# 2. Pull the latest code
git pull origin main

# 3. Install dependencies
uv sync

# 4. Start the application
# Migration will run automatically
uv run uvicorn main:app --reload

# 5. Verify migration succeeded
sqlite3 data/links.db "SELECT value FROM metadata WHERE name = 'db_version';"
# Should output: 2.0.0

Manual Migration (if needed)

If automatic migration fails, you can run the migration script manually:

# Backup first!
cp data/links.db data/links.db.backup

# Run migration script
sqlite3 data/links.db < sql_scripts/v1_to_v2.sql

# Verify
sqlite3 data/links.db "SELECT name FROM sqlite_master WHERE type='table';"
# Should show: links, metadata, tags, tagmap

Rolling Back a Migration

If you need to roll back:

# Stop the application first
docker stop startpage
# or kill the uvicorn process

# Restore from backup
cp data/links.db.backup data/links.db

# Checkout previous version
git checkout v1.2.3

# Restart application
docker start startpage

Migration Troubleshooting

Backup and Restore

Creating a Backup

Local deployment:

cp data/links.db data/links.db.backup-$(date +%Y%m%d)

Docker deployment:

cp ~/.config/startpage/links.db ~/.config/startpage/links.db.backup-$(date +%Y%m%d)

Automated Backups

Create a cron job for daily backups:

# Edit crontab
crontab -e

# Add this line (runs daily at 2 AM)
0 2 * * * cp ~/.config/startpage/links.db ~/.config/startpage/backups/links-$(date +\%Y\%m\%d).db

Restoring from Backup

# Stop the application
docker stop startpage

# Restore the backup
cp data/links.db.backup-20250101 data/links.db

# Start the application
docker start startpage

Exporting Data

Export to SQL format:

sqlite3 data/links.db .dump > startpage-export.sql

Export links to CSV:

sqlite3 -header -csv data/links.db "SELECT * FROM links;" > links.csv

Key Application Routes

StartPage exposes several important routes for end users and administrators. Understanding these helps with deployment, monitoring, and integration.

End User Routes

Admin & API Routes

Documentation Routes

Note: app route /docs is the FastAPI docs UI. This static page lives in docs/index.html for the project documentation site.

Configuration

Application Settings

Settings are editable via the /settings screen (also linked in the app's navbar) and persisted to config.toml at the project root. Set STARTPAGE_CONFIG_PATH to point at a different writable TOML file if you want to store settings elsewhere.

Modifying Settings

Prefer the UI whenever possible. For automation/headless workflows, edit config.toml with your favorite editor or provision a file before booting the app:

# config.toml
[frecency]
batch_size = 50
max_rank = 2000

[temp_links]
enabled = true
default_ttl_hours = 12
max_custom_hours = 72
purge_interval_seconds = 900

Prometheus Metrics Endpoint

StartPage exposes a Prometheus-compatible endpoint at /metrics. Access is restricted by an IP/CIDR whitelist stored in the SQLite metadata table under metrics_whitelist.

Trusted proxy CIDRs used for forwarded /metrics headers are stored in metadata under trusted_proxy_cidrs.

Use the CLI helper to inspect and update the allow-list and trusted proxy entries:

# Local development usage
uv run python -m services.config_cli metrics-whitelist show

# Append a new CIDR/IP without replacing existing entries
uv run python -m services.config_cli metrics-whitelist add 10.0.0.0/8

# Remove an existing CIDR/IP entry
uv run python -m services.config_cli metrics-whitelist remove 10.0.0.0/8

# Replace allow-list entries
uv run python -m services.config_cli metrics-whitelist set 127.0.0.1/32 10.0.0.0/8

# Reset to local-only defaults (127.0.0.1 and ::1)
uv run python -m services.config_cli metrics-whitelist reset

# Clear all entries (blocks all /metrics clients)
uv run python -m services.config_cli metrics-whitelist clear

# Show trusted proxy CIDRs used for forwarded /metrics headers
uv run python -m services.config_cli trusted-proxies show

# Add your reverse proxy/container bridge source IP or CIDR
uv run python -m services.config_cli trusted-proxies add 172.17.0.1/32

# Docker shortcut (built into the image)
docker exec -it startpage startpage-config metrics-whitelist add 10.0.0.0/8
docker exec -it startpage startpage-config trusted-proxies add 172.17.0.1/32

When running behind nginx, pass the real client address explicitly so whitelist checks work correctly:

location / {
    proxy_pass http://127.0.0.1:8001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $remote_addr;
}

Forwarded headers are only trusted when the direct client IP matches the trusted proxy CIDR list (default: 127.0.0.1/32,::1/128).

If nginx runs from another host/container network, add that proxy source CIDR with the CLI (for example trusted-proxies add 172.18.0.0/16).

Trusted proxy CIDR updates apply immediately because /metrics reads these values from metadata for each request.

The OpenAPI docs at /docs (and /redoc) include the /metrics operation details and 403 behavior when the source IP is not whitelisted.

PromQL Quick Tests

Replace job="startpage" if your Prometheus scrape job uses a different name.

# Scrape status
up{job="startpage"}

# Core gauges
startpage_links_total{job="startpage"}
startpage_temp_links_total{job="startpage"}
startpage_tags_total{job="startpage"}
startpage_rank_sum{job="startpage"}

# Temporary-link percentage
100 * startpage_temp_links_total{job="startpage"} / clamp_min(startpage_links_total{job="startpage"}, 1)

# /metrics traffic in last 24 hours
increase(startpage_metrics_requests_total{job="startpage"}[24h])
increase(startpage_metrics_denied_total{job="startpage"}[24h])

# Denied percentage in last 24 hours
100 * increase(startpage_metrics_denied_total{job="startpage"}[24h]) / clamp_min(increase(startpage_metrics_requests_total{job="startpage"}[24h]), 1)

# App uptime (hours)
startpage_metrics_uptime_seconds{job="startpage"} / 3600

# Whitelist entry count
startpage_metrics_whitelist_entries{job="startpage"}

# Counter resets in 7 days (process restart hint)
resets(startpage_metrics_requests_total{job="startpage"}[7d])

Frecency Algorithm Parameters

The ranking formula is defined in services/db_utils.py:

score = 10000 * rank * (3.75 / ((0.0001 * (current_time - last_accessed) + 1) + 0.25))

• rank increments by 1 on each click
• Links with rank < 1 are automatically deleted when total ranks exceed max_rank
• Remaining ranks are reduced by 1% during cleanup

Temporary Link Controls

Mark a link as temporary from the add/edit form to set an automatic expiration (24 hours by default). Temporary links are highlighted in the UI and removed automatically when they expire.

Use /settings to toggle the feature, change the default duration, cap the custom duration, and adjust the cleanup interval. Updates are persisted to config.toml and apply immediately.

Monitoring with Statistics

The /stats route provides a comprehensive analytics dashboard for monitoring link health and usage patterns. This is valuable for administrators who want to understand how the system is being used and identify potential issues before they occur.

Use Cases:

• Monitor when automatic pruning will trigger (when sum rank approaches max_rank)
• Identify stale links that haven't been accessed in months
• Verify that frequently-used links have sufficient rank to avoid accidental deletion
• Understand usage patterns to optimize batch size and max rank settings
• Generate periodic reports for link collection health

Troubleshooting

sqlite3 data/links.db "PRAGMA integrity_check;"

Getting Help

For additional support:

• Check application logs
• Review GitHub issues
• Open a new issue with logs and configuration details