experiments/homebox: use shared PostgreSQL instead of SQLite

Made-with: Cursor

Author: romkey

experiments/homebox/.env.example

@@ -4,6 +4,17 @@ IMAGE_VERSION=latest
 # Optional: timezone inside the container
 # TZ=America/Los_Angeles
 
-# HomeBox merges /data/config.yml with environment variables using the HBOX_
-# prefix (see https://homebox.software/ ). Example behind a reverse proxy:
+# PostgreSQL password for homebox_user (create DB/user first; see README).
+# Do not commit real values — keep them only in .env.
+HBOX_DATABASE_PASSWORD=
+
+# Optional overrides (defaults match config.yml when copied from config/config.yml.default):
+# HBOX_DATABASE_DRIVER=postgres
+# HBOX_DATABASE_HOST=postgresql
+# HBOX_DATABASE_PORT=5432
+# HBOX_DATABASE_USERNAME=homebox_user
+# HBOX_DATABASE_DATABASE=homebox_db
+# HBOX_DATABASE_SSL_MODE=disable
+
+# HomeBox merges /data/config.yml with HBOX_* variables (see https://homebox.software/ ).
 # HBOX_OPTIONS_TRUST_PROXY=true

experiments/homebox/README.md

@@ -1,44 +1,44 @@
 # homebox (experiment)
 
-[HomeBox](https://github.com/sysadminsmedia/homebox) is a self-hosted home inventory and organization app (SQLite, low resource use). This stack runs the maintained **`ghcr.io/sysadminsmedia/homebox`** image (continuation of the original hay-kot project).
+[HomeBox](https://github.com/sysadminsmedia/homebox) is a self-hosted home inventory and organization app. This stack runs the maintained **`ghcr.io/sysadminsmedia/homebox`** image and uses the **shared PostgreSQL** service (`postgresql` on `postgres-net`) for the database; uploads and `config.yml` stay on **`../../lib/homebox`** (mounted at `/data`).
 
 ## Configuration
 
-### Environment
+### 1. PostgreSQL database
 
-Copy `.env.example` to `.env`:
+Create a dedicated database and user with the shared cluster helper (from **`apps/postgresql`**):
 
 ```bash
-cp .env.example .env
+../../apps/postgresql/bin/mkdb.sh homebox
 ```
 
-Set `IMAGE_VERSION` if you want to pin a tag other than `latest` (see [GHCR packages](https://github.com/sysadminsmedia/homebox/pkgs/container/homebox)).
-
-Additional runtime tuning can use `HBOX_*` variables; see the [HomeBox documentation](https://homebox.software/).
+That creates **`homebox_db`** owned by **`homebox_user`** and prints a password. Put that password in **`.env`** as **`HBOX_DATABASE_PASSWORD`** (see `.env.example`).
 
-### Config file (required)
+### 2. Environment
 
-The image expects **`/data/config.yml`** on the persistent volume (same directory as the SQLite database).
+Copy `.env.example` to **`.env`** and set **`HBOX_DATABASE_PASSWORD`** (and **`IMAGE_VERSION`** if you pin a tag).
 
-1. Ensure the data directory exists (repository convention):
+```bash
+cp .env.example .env
+```
 
-   ```bash
-   mkdir -p ../../lib/homebox
-   ```
+### 3. Config file (required)
 
-2. Install the config once:
+The image expects **`/data/config.yml`** on the persistent volume.
 
-   ```bash
-   cp config/config.yml.default ../../lib/homebox/config.yml
-   ```
+```bash
+mkdir -p ../../lib/homebox
+cp config/config.yml.default ../../lib/homebox/config.yml
+```
 
-3. Edit `../../lib/homebox/config.yml` as needed (public URL / hostname, OIDC, mailer, registration policy, etc.).
+Edit **`../../lib/homebox/config.yml`** if you change DB name, user, host, or TLS. By default it targets **`postgresql:5432`** with **`ssl_mode: disable`** on the internal Docker network.
 
-For **`latest-rootless`** or **`latest-hardened`**, the upstream image may require ownership on `/data` (e.g. `chown 65532:65532`); see the [HomeBox quick start](https://homebox.software/en/quick-start/).
+For **`latest-rootless`** or **`latest-hardened`**, see the [HomeBox quick start](https://homebox.software/en/quick-start/) for `/data` ownership (e.g. `chown 65532:65532`).
 
 ## Networks
 
-- **`nginx-proxy-net`** — attach your reverse proxy vhost to the container’s internal port **7745**.
+- **`postgres-net`** — database (`postgresql` hostname)
+- **`nginx-proxy-net`** — reverse proxy to container port **7745**
 
 ## Usage
 
@@ -62,4 +62,5 @@ docker compose logs -f
 
 ### Backup
 
-Back up the directory **`../../lib/homebox`** (includes `config.yml`, SQLite DB, and uploads).
+- **PostgreSQL:** include `homebox_db` in your normal DB backups (e.g. `BACKUP_DATABASE_URLS` pattern used elsewhere in this repo).
+- **Files:** back up **`../../lib/homebox`** (`config.yml`, uploads under the storage prefix on `/data`).

experiments/homebox/config/config.yml.default

@@ -1,19 +1,26 @@
 # Copy to ../../lib/homebox/config.yml and adjust.
-# The container entrypoint expects the config at /data/config.yml (same volume as SQLite).
+# The container entrypoint expects the config at /data/config.yml (uploads live under /data).
 
 mode: production
 
 web:
   port: "7745"
   # Behind nginx-proxy, `trust_proxy` below (or HBOX_OPTIONS_TRUST_PROXY=true) is recommended.
 
+# File/blob storage (attachments). Matches the upstream image defaults; data is on the /data volume.
 storage:
   prefix_path: data
   conn_string: "file:///?no_tmp_dir=true"
 
 database:
-  driver: sqlite3
-  sqlite_path: "/data/homebox.db?_pragma=busy_timeout=2000&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite"
+  driver: postgres
+  host: postgresql
+  port: "5432"
+  username: homebox_user
+  database: homebox_db
+  # Use `disable` on the internal Docker network unless PostgreSQL is using TLS.
+  ssl_mode: disable
+  # Prefer setting the password in .env as HBOX_DATABASE_PASSWORD (not committed).
 
 options:
   trust_proxy: true

experiments/homebox/docker-compose.yml

@@ -12,6 +12,7 @@ services:
 #     - 3100:7745
     networks:
       - proxy
+      - db
     healthcheck:
       test:
         [
@@ -32,3 +33,6 @@ networks:
   proxy:
     external: true
     name: nginx-proxy-net
+  db:
+    external: true
+    name: postgres-net