diff --git a/.github/demo.gif b/.github/demo.gif
new file mode 100644
index 0000000..5d3cf15
Binary files /dev/null and b/.github/demo.gif differ
diff --git a/.github/demo.tape b/.github/demo.tape
new file mode 100644
index 0000000..c1cd8f8
--- /dev/null
+++ b/.github/demo.tape
@@ -0,0 +1,31 @@
+# VHS demo tape for automa
+# Run: vhs .github/demo.tape
+
+Output .github/demo.gif
+
+Set Shell bash
+Set FontSize 15
+Set Width 900
+Set Height 500
+Set Padding 20
+Set Theme { "name": "automa", "black": "#0f172a", "red": "#ef4444", "green": "#22c55e", "yellow": "#eab308", "blue": "#3b82f6", "magenta": "#a855f7", "cyan": "#06b6d4", "white": "#f8fafc", "brightBlack": "#64748b", "brightRed": "#f87171", "brightGreen": "#4ade80", "brightYellow": "#facc15", "brightBlue": "#60a5fa", "brightMagenta": "#c084fc", "brightCyan": "#22d3ee", "brightWhite": "#ffffff", "background": "#0f172a", "foreground": "#f8fafc", "selection": "#334155", "cursor": "#38bdf8" }
+
+Sleep 500ms
+
+Type "./automa help"
+Enter
+Sleep 3s
+
+Type "./automa list"
+Enter
+Sleep 3s
+
+Type "./automa -y deploy uptime-kuma"
+Enter
+Sleep 6s
+
+Type "./automa status"
+Enter
+Sleep 3s
+
+Sleep 1s
diff --git a/README.md b/README.md
index ba89183..f4fada8 100644
--- a/README.md
+++ b/README.md
@@ -3,16 +3,22 @@
- Self-hosted Docker Compose deployer
- Interactive CLI to deploy Forgejo, Nextcloud, Minecraft, and more in seconds.
+ One command to deploy your self-hosted stack.
+ Interactive CLI for Docker Compose — guided setup, auto-generated secrets, zero YAML editing.
- 
- 
- 
- 
+ 
+ 
+ 
+ 
+
+
+
+
+
+ 
---
@@ -25,31 +31,53 @@ cd ~/automa
./automa deploy
```
-That's it. The CLI walks you through everything interactively.
+That's it. The installer checks prerequisites, clones the repo, and you're ready to deploy.
-## What is automa?
+## Features
-**automa** is a single bash script that turns a collection of Docker Compose projects into a deploy-ready toolkit. No YAML editing, no manual `docker compose` commands — just answer a few questions and your services are live.
+- **Interactive CLI** — select projects from a numbered menu, guided `.env` setup with hints
+- **Zero config** — sensible defaults for every project, passwords and secrets auto-generated
+- **Non-interactive mode** — `automa -y deploy` accepts all defaults for CI/scripts
+- **Self-contained projects** — each is an independent directory, no shared dependencies
+- **Production-ready** — health checks, security hardening, least-privilege containers
+- **Extensible** — drop in a `compose.yaml` + `.env.example` and automa discovers it
-- **Zero config** — sensible defaults for every project, secrets auto-generated
-- **Interactive** — guided setup with hints, validation, and color-coded output
-- **Non-interactive** — `automa -y deploy` for CI/scripts, accepts all defaults
-- **Self-contained** — each project is an independent directory, no shared dependencies
-- **Portable** — pure bash, works on any Linux with Docker
+## Bundled Projects
-## Available Projects
+| Project | Description | Default Port | Upstream |
+|---------|-------------|:------------:|----------|
+| **Forgejo** | Self-hosted Git service (Gitea fork) | `3000` | [forgejo.org](https://forgejo.org) |
+| **Nextcloud** | Private cloud with MariaDB + Redis | `8080` | [nextcloud.com](https://nextcloud.com) |
+| **Uptime Kuma** | Uptime monitoring dashboard | `3001` | [GitHub](https://github.com/louislam/uptime-kuma) |
+| **Tailscale** | Mesh VPN client + optional DERP relay | host | [tailscale.com](https://tailscale.com) |
+| **Filesuite** | Cloudreve cloud storage + qBittorrent | `5212` `8090` | [cloudreve.org](https://cloudreve.org) |
+| **Minecraft** | Fabric server (itzg/minecraft-server) | `25565` | [Docs](https://docker-minecraft-server.readthedocs.io) |
+| **TeamSpeak** | Voice communication server | `9987/udp` | [teamspeak.com](https://teamspeak.com) |
-| Project | Description | Upstream |
-|---------|-------------|----------|
-| **Forgejo** | Self-hosted Git service (Gitea fork) | [forgejo.org](https://forgejo.org) |
-| **Nextcloud** | Private cloud with MariaDB + Redis | [nextcloud.com](https://nextcloud.com) |
-| **Uptime Kuma** | Uptime monitoring dashboard | [GitHub](https://github.com/louislam/uptime-kuma) |
-| **Tailscale** | Mesh VPN client + optional DERP relay | [tailscale.com](https://tailscale.com) |
-| **Filesuite** | Cloudreve cloud storage + qBittorrent | [cloudreve.org](https://cloudreve.org) |
-| **Minecraft** | Fabric server (itzg/minecraft-server) | [Docs](https://docker-minecraft-server.readthedocs.io) |
-| **TeamSpeak** | Voice communication server | [teamspeak.com](https://teamspeak.com) |
+
+Project-specific notes
-> Adding your own project? Just create a directory with `compose.yaml` and `.env.example` — automa discovers it automatically.
+#### Tailscale
+
+Uses Docker Compose profiles — deploy only the VPN client or include the DERP relay:
+
+```bash
+# Tailscale client only
+docker compose --profile tailscale up -d
+
+# Client + DERP relay
+docker compose --profile derp up -d
+```
+
+#### Nextcloud
+
+Ships with MariaDB 11 and Redis 7 as backing services. All three containers have health checks with `depends_on` ordering. First startup takes ~60s for database migration.
+
+#### Minecraft
+
+Uses the [itzg/minecraft-server](https://docker-minecraft-server.readthedocs.io) image with Fabric mod loader. Mods go in `minecraft/data/mods/`. First startup takes ~2 minutes to download server files.
+
+
## Usage
@@ -70,33 +98,38 @@ automa list # list all projects
```
~/automa/
-├── automa # CLI entry point (single script)
+├── automa # CLI entry point (single bash script)
├── install.sh # curl-pipe-bash installer
├── forgejo/
│ ├── compose.yaml # Docker Compose definition
-│ ├── .env.example # Template with metadata + defaults
+│ ├── .env.example # Template with @metadata + defaults
│ └── .env # Your config (gitignored, created by CLI)
├── nextcloud/
│ └── ...
└── ...
```
-Each project directory is fully self-contained:
+Each `.env.example` carries metadata that the CLI reads:
-- **`compose.yaml`** — production-ready with health checks, resource hints, and security hardening
-- **`.env.example`** — annotated template with `@name`, `@desc`, `@url`, `@port` metadata that the CLI reads
-- **`.env`** — your configuration, auto-generated with safe defaults and random secrets
+```bash
+# @name Forgejo
+# @desc Self-hosted Git service (Gitea fork)
+# @url https://forgejo.org
+# @port FORGEJO_HTTP_PORT
+```
+
+The CLI uses these annotations to show project names, descriptions, docs links, and access URLs — all without extra configuration files.
## Requirements
-| Dependency | Minimum |
-|------------|---------|
-| Docker | 20.10+ |
-| Docker Compose | v2 (plugin) |
-| Bash | 4.0+ |
-| Git | any |
+| Dependency | Minimum | Check |
+|------------|---------|-------|
+| Docker | 20.10+ | `docker --version` |
+| Docker Compose | v2 (plugin) | `docker compose version` |
+| Bash | 4.0+ | `bash --version` |
+| Git | any | `git --version` |
-The installer checks all prerequisites automatically.
+The installer verifies all prerequisites automatically.
## Uninstall
@@ -106,22 +139,17 @@ cd ~/automa
cd ~ && rm -rf ~/automa # remove automa
```
-Data volumes are stored inside each project's `data/` directory and will be removed with the above command. Back up first if needed.
+Data is stored in each project's `data/` directory. Back up before removing if needed.
## Contributing
-Contributions are welcome! To add a new project:
+Contributions welcome! To add a new project:
-1. Create a new directory: `mkdir myproject`
-2. Add a `compose.yaml` with health checks
-3. Add a `.env.example` with metadata headers:
- ```bash
- # @name My Project
- # @desc Short description shown in CLI
- # @url https://project-homepage.com
- # @port PORT_VAR_NAME
- ```
-4. Open a pull request
+1. Create a directory with `compose.yaml` (include health checks)
+2. Add `.env.example` with metadata headers (`@name`, `@desc`, `@url`, `@port`)
+3. Open a pull request
+
+See existing projects for reference.
## License