From 20117a2a3f2bc865f28ebfbbbbc8af8001ec0daf Mon Sep 17 00:00:00 2001
From: Cesar Flores <dev@esauflores.com>
Date: Sat, 7 Mar 2026 04:07:16 +0700
Subject: [PATCH] docs: Add README.md for project documentation and usage
 instructions

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cfcf565
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# resources-databases
+
+Custom database Docker images, built for local development and self-hosted deployments.
+
+## Supported Variants
+
+| Variant    | Base Image             |
+| ---------- | ---------------------- |
+| `postgres` | `postgres:18.3-alpine` |
+
+## Prerequisites
+
+- [mise](https://mise.jdx.dev/) — manages tool versions
+- [Docker](https://docs.docker.com/get-docker/) with Compose plugin
+
+```bash
+mise install
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and adjust as needed:
+
+```bash
+cp .env.example .env
+```
+
+| Variable            | Default    | Description                           |
+| ------------------- | ---------- | ------------------------------------- |
+| `REGISTRY_URL`      | _(empty)_  | Container registry URL for publishing |
+| `POSTGRES_USER`     | `postgres` | Postgres superuser name               |
+| `POSTGRES_PASSWORD` | `postgres` | Postgres superuser password           |
+| `POSTGRES_DB`       | `postgres` | Default database name                 |
+| `POSTGRES_PORT`     | `5432`     | Host port mapped to Postgres          |
+
+## Usage
+
+```bash
+# Build image locally
+just build [db]
+
+# Start database (waits until healthy)
+just db-up [db]
+
+# Stop database and remove volumes
+just db-down [db]
+
+# Run tests
+just test [db]
+
+# Build and push to registry
+just publish [db]
+```
+
+`db` defaults to `postgres` when not specified.
+
+## CI/CD
+
+The GitHub Actions workflow (`.github/workflows/test-and-push.yml`) triggers on `v*` tag pushes:
+
+1. **Test** — spins up the database and verifies connectivity
+2. **Publish** — builds and pushes the image to the configured registry
+
+Required repository secrets: `REGISTRY_URL`, `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`.
+
+## Adding a New Variant
+
+1. Create `<db>/Dockerfile` and `<db>/compose.yml`
+2. Add a `_test-<db>` recipe and a case entry in `test` in the `Justfile`
+3. Add `<db>` to the `matrix.db` list in `.github/workflows/test-and-push.yml`
+4. Add any new env vars to `.env.example`