chore: update documentation for improved clarity and organization

Author: axadrn

README.md

@@ -26,6 +26,8 @@ One TUI can manage multiple VPS servers via profiles. Create or switch profiles
 
 [deeploy.sh/docs](https://deeploy.sh/docs)
 
+`content/docs` is the source of truth for setup, operations, domains, and pod configuration.
+
 ## Development
 
 ```bash
@@ -34,9 +36,7 @@ task dev:tui                # TUI client
 task dev:docs               # Docs website
 ```
 
-`docker-compose.override.yml` applies local Traefik dev settings (HTTP + dashboard).
-It is auto-loaded by Docker Compose during normal local `docker compose` commands.
-In dev, it also disables the `deeploy` container so you can run the server via `go run ./cmd/server`.
+`docker-compose.override.yml` applies local Traefik dev settings and is auto-loaded by Docker Compose in local runs.
 
 ## License
 

content/docs/configuration.md

@@ -0,0 +1,34 @@
+---
+title: Configuration
+description: Server secrets and rotation
+order: 3
+---
+
+deeploy generates secure server secrets automatically on first install.
+
+## Server Secrets
+
+- `JWT_SECRET`
+- `ENCRYPTION_KEY`
+
+The install script generates both automatically on first install and writes them to `/opt/deeploy/.env`.
+
+You normally do not need to touch them.
+
+## Important
+
+- Change `ENCRYPTION_KEY` only before you store real data.
+- If you change `ENCRYPTION_KEY` later, previously encrypted values in the database cannot be decrypted.
+- Changing `JWT_SECRET` logs out existing sessions (users must log in again).
+
+## If You Must Change Secrets
+
+1. SSH to your server.
+2. Open `/opt/deeploy/.env`.
+3. Replace the secret(s).
+4. Restart the stack:
+   ```bash
+   cd /opt/deeploy
+   docker compose up -d --force-recreate
+   ```
+5. Verify login and app behavior.

content/docs/deploying.md

@@ -1,7 +1,7 @@
 ---
 title: Deploying
 description: Deploy your first app
-order: 3
+order: 4
 ---
 
 Deploy your first application step by step.
@@ -24,16 +24,32 @@ A pod is a single deployable application. One pod = one container.
 - **Branch** - The branch to deploy (default: `main`)
 - **Dockerfile** - Path to your Dockerfile (default: `Dockerfile`)
 
-For private repositories, you'll need to add a [Git Token](/docs/private-repos) first.
+For private repositories, select a Git token in the pod form.
+Git tokens are managed in **Settings → Tokens** (create/edit/delete there).
 
-## 3. Add a Domain
+If your app needs runtime config, add it in [Pod Environment Variables](/docs/pod-env-vars).
+
+## 3. Set Pod Vars (Optional)
+
+If your app needs runtime variables:
+
+1. Open the pod
+2. Go to **Vars** (`4`)
+3. Press `e` to edit
+4. Save with `Ctrl+S`
+
+Then restart or redeploy the pod to apply changes.
+
+## 4. Add a Domain
 
 Your pod needs a domain to be accessible. You have two options:
 
 - **Auto-generated** - Instant subdomain like `pod-abc123.1.2.3.4.sslip.io`
 - **Custom** - Your own domain like `myapp.example.com` (requires [DNS setup](/docs/domains))
 
-## 4. Deploy
+After domain changes, run **Deploy** or **Restart** so routing updates are applied.
+
+## 5. Deploy / Restart
 
 Hit "Deploy" and watch the build logs. The process:
 
@@ -54,4 +70,6 @@ Once complete, your app is live at the domain URL.
 
 **Redeploy** - Pull latest code and rebuild
 
+**Vars** - Edit runtime environment variables for the pod
+
 To update your app, just push to your repository and hit "Deploy" again.

content/docs/domains.md

@@ -1,7 +1,7 @@
 ---
 title: Domains
 description: Custom domains and HTTPS setup
-order: 4
+order: 6
 ---
 
 ## Server Domain
@@ -29,10 +29,21 @@ order: 4
 
 **Note:** Ports 80 and 443 must be open on your server for SSL to work.
 
+### Verify Server HTTPS
+
+After setting the server domain:
+
+1. Confirm your TUI profile/server URL uses `https://...`
+2. Confirm certificate provisioning completed successfully
+3. If it fails, verify DNS propagation and that ports 80/443 are open
+
 ## Pod Domains
 
 Each pod needs at least one domain to be accessible.
 
+Domain changes are not applied to a running container automatically.
+After adding, editing, or deleting pod domains, run **Deploy** or **Restart** to apply routing changes.
+
 ### Auto-Generated Domains
 
 The quickest way to get started. Deeploy generates a subdomain using [sslip.io](https://sslip.io):
@@ -58,7 +69,7 @@ For production apps, use your own domain:
 
    Pod → Domains → New → Enter `myapp.example.com`
 
-3. **Deploy**
+3. **Deploy or Restart**
 
    SSL certificate is automatically provisioned.
 

content/docs/getting-started.md

@@ -6,6 +6,8 @@ order: 2
 
 Get up and running with deeploy in minutes.
 
+No manual environment-variable setup is required for the standard installation.
+
 ## Requirements
 
 **Server (VPS)**
@@ -25,6 +27,8 @@ SSH into your VPS and run:
 curl -fsSL https://deeploy.sh/server.sh | sudo bash
 ```
 
+On first install, the script generates required server secrets automatically.
+
 ### Options
 
 ```bash
@@ -39,6 +43,8 @@ curl -fsSL https://deeploy.sh/server.sh | sudo bash -s v0.1.0
 
 SQLite is used by default - zero configuration needed.
 
+For full server config details, see [Configuration](/docs/configuration).
+
 ## Install TUI
 
 On your local machine:
@@ -58,6 +64,8 @@ curl -fsSL https://deeploy.sh/tui.sh | bash -s v0.1.0
 
 Run `deeploy` to launch the TUI and connect to your server.
 
+After connecting, set your [Server Domain](/docs/domains) to enable HTTPS between TUI and server.
+
 After first login, you can add more servers as separate profiles and switch between them later.
 This lets you manage multiple VPS instances from one local TUI setup.
 

content/docs/pod-env-vars.md

@@ -0,0 +1,46 @@
+---
+title: Pod Environment Variables
+description: Manage runtime environment variables for your pods
+order: 7
+---
+
+Use Pod Environment Variables (Vars tab) to provide runtime config to your app containers.
+
+## Where to Edit
+
+In the TUI:
+
+1. Open a pod
+2. Switch to the **Vars** tab (`4` or `[` / `]`)
+3. Press `e` to edit
+4. Enter variables in `KEY=value` format (one per line)
+5. Press `Ctrl+S` to save
+
+## Format Rules
+
+- One variable per line
+- Format must be `KEY=value`
+- Empty lines are ignored
+- Duplicate keys are resolved by last entry
+
+## When Changes Apply
+
+Saved vars are stored for the pod and applied to the container on deploy/redeploy/restart.
+
+Recommended flow after changes:
+
+1. Save vars in **Vars** tab
+2. Trigger **Restart** (`R`) or **Deploy** (`D`)
+
+## Security Notes
+
+- Pod vars are stored encrypted server-side
+- They are used for container runtime environment injection
+- Keep secrets out of repository files and Dockerfiles when possible
+
+## Common Mistakes
+
+- Missing `=` in a line
+- Trailing spaces in keys
+- Editing vars but forgetting to restart/redeploy
+- Setting app vars in server config instead of pod vars

content/docs/private-repos.md

@@ -1,7 +1,7 @@
 ---
 title: Private Repositories
 description: Deploy from private Git repositories
-order: 5
+order: 8
 ---
 
 To deploy from private repositories, you need to add a Git token.

content/docs/tui.md

@@ -1,7 +1,7 @@
 ---
 title: Using the TUI
 description: Navigate the terminal interface
-order: 6
+order: 5
 ---
 
 The deeploy TUI (Terminal User Interface) is built for keyboard-driven workflows.
@@ -46,6 +46,8 @@ Inside a pod, use:
 - `n`, `g`, `o`, `e`, `d` for domain actions (Domains tab)
 - `e` to edit vars, `Ctrl+S` to save, `Esc` to cancel (Vars tab)
 
+For detailed vars behavior and best practices, see [Pod Environment Variables](/docs/pod-env-vars).
+
 ## Themes
 
 Open themes from the **Settings** panel:

content/docs/updating.md

@@ -1,7 +1,7 @@
 ---
 title: Updating
 description: Update deeploy to the latest version
-order: 7
+order: 9
 ---
 
 ## Update Server
@@ -14,6 +14,12 @@ curl -fsSL https://deeploy.sh/server.sh | sudo bash
 
 This pulls the latest Docker image and restarts the server. Your data is preserved.
 
+What is preserved:
+
+- Existing `.env` with your generated secrets
+- Database data in mounted volumes
+- Existing deployment records/projects/pods
+
 ### Specific Version
 
 ```bash
@@ -37,3 +43,12 @@ curl -fsSL https://deeploy.sh/tui.sh | bash -s v0.2.0
 ## Check Version
 
 The TUI shows your current version and the latest available version in the Settings info panel and status/header area.
+
+## Quick Verification After Update
+
+1. Check health endpoint:
+   ```bash
+   curl -fsSL http://YOUR_SERVER_IP:8090/api/health
+   ```
+2. Open the TUI and confirm server/version info is visible.
+3. Open an existing pod and verify logs/deploy actions work.