Add README.md

README.md

@@ -1,3 +1,41 @@
-# demo-stacks
+# Citadel example stacks
 
-Independent Voting App and WordPress Git Stacks in one Citadel demo monorepo.
+Two independent applications in one Git repository demonstrate Citadel's
+monorepo support. Register this repository once in **Git Repositories**, then
+create a Git Stack for each application.
+
+| Stack | Compose path | Working directory | Watch path |
+| --- | --- | --- | --- |
+| Voting app | `voting-app/compose.yaml` | `voting-app` | `voting-app/**` |
+| WordPress | `wordpress/compose.yaml` | `wordpress` | `wordpress/**` |
+
+Select `main` and use **Discover compose paths** to find both definitions.
+Compose paths are relative to the repository root. Start with automatic updates
+disabled and deploy each Stack explicitly. Updating one application's folder
+should not mark the other Stack outdated.
+
+The [Docker voting sample](https://github.com/dockersamples/example-voting-app)
+demonstrates five services, separate networks, health checks, and a persistent
+PostgreSQL volume. Its upstream images hardcode the `postgres` / `postgres`
+sample database credentials. Use only disposable votes; never reuse these
+credentials or expose the database port.
+
+WordPress demonstrates a persistent website and MariaDB database. Bind
+`WORDPRESS_DB_PASSWORD` to a Citadel Secret before deployment. Generate a separate
+password in each environment; do not commit it to this repository. Complete
+WordPress installation privately before exposing the site to visitors.
+
+Web ports bind to loopback for access through a host reverse proxy or SSH
+tunnel. Database ports are not published. Supply these non-secret variables in
+each Stack to avoid host-port collisions:
+
+| Variable | Preview | Demo |
+| --- | --- | --- |
+| `VOTE_PORT` | `18402` | `28402` |
+| `RESULT_PORT` | `18403` | `28403` |
+| `WORDPRESS_PORT` | `18404` | `28404` |
+
+Each environment uses its own Docker engine, Forgejo repository instance, Stack
+resources, networks, and volumes. Sharing these definitions does not share data.
+Image tags are intentionally visible in the examples; operators should review
+resolved images before enabling automatic updates.