# Caddy Deployment Helpers

## Files

- `install_caddy.sh`: prepares Caddy in `binary` or `docker` mode.
- `.bash_caddy`: helper script fetched by `install_caddy.sh` from `HELPER_SCRIPT_URL` and deployed with the target config.
- `tests/test_install_caddy.sh`: shell regression tests.

The installer automatically adds a shell hook to the current user's rc file so `caddy` is available in new shell sessions. The hook points to the deployed helper, not the repository copy.
At the top of `install_caddy.sh`, set `HELPER_SCRIPT_URL` if you want to publish the helper from a different URL.

## Modes

### Binary

- Downloads the latest Caddy release by default from the upstream GitHub releases redirect.
- Writes the binary to `/usr/local/bin/caddy`.
- Writes config to `/etc/caddy/Caddyfile`.
- Writes logs to `/etc/caddy/logs`.
- Uses `/etc/caddy/state` for Caddy state and certificate storage.
- Keeps static files disabled by default.
- Creates `/etc/caddy/site` only when `--enable-static-site` is used.
- Writes `/etc/systemd/system/caddy.service` based on the upstream `caddyserver/dist` unit file.

Generated paths:

- `/etc/caddy`: main config root for Caddy.
- `/etc/caddy/Caddyfile`: generated Caddyfile used by the service.
- `/etc/caddy/.bash_caddy`: deployed helper script used by shell startup hooks.
- `/etc/caddy/.helper.env`: helper settings generated by the installer, currently used for the preferred editor.
- `/etc/caddy/logs`: runtime and access log directory.
- `/etc/caddy/state`: Caddy state directory for certificates, ACME account data, renew state, and local storage.
- `/etc/caddy/site`: optional static site root, created only when `--enable-static-site` is used.
- `/usr/local/bin/caddy`: installed Caddy binary.
- `/etc/systemd/system/caddy.service`: generated systemd unit for binary mode.

### Docker

- Uses `caddy:latest` by default.
- Uses `~/projects/caddy` by default.
- Uses `network_mode: host` because this helper targets gateway-style deployments on Linux hosts.
- Writes `compose.yml` to `~/projects/caddy/compose.yml`.
- Writes config to `~/projects/caddy/conf/Caddyfile`.
- Mounts logs to `~/projects/caddy/logs`.
- Mounts state to `~/projects/caddy/data` and `~/projects/caddy/config`.
- Keeps static files disabled by default.
- Mounts `~/projects/caddy/site:/srv` only when `--enable-static-site` is used.

Generated paths under `~/projects/caddy`:

- `conf`: stores `Caddyfile` and any extra config files mounted to `/etc/caddy`.
- `.bash_caddy`: deployed helper script used by shell startup hooks.
- `.helper.env`: helper settings generated by the installer, currently used for the preferred editor.
- `compose.yml`: generated Docker Compose file for the Caddy container.
- `logs`: host-side runtime and access log directory mounted to `/var/log/caddy`.
- `data`: host-side `/data` mount for persisted certificates and Caddy-managed runtime data.
- `config`: host-side `/config` mount for persisted config state used by the official Docker image.
- `site`: optional static site directory mounted to `/srv` only when `--enable-static-site` is used.

## Install

```bash
cd bitfennec_simple_page/http/linux/caddy
bash install_caddy.sh <binary|docker> [options]
```

| Option | Purpose | Default |
| --- | --- | --- |
| `binary` / `docker` | Select deployment mode | `binary` |
| `--enable-static-site` | Create and wire the optional static site directory | disabled |
| `--editor <name>` | Set the editor used by `caddy edit` | `vim` |
| `--docker-root <path>` | Override Docker root directory | `~/projects/caddy` |
| `--version <x.y.z>` | Pin a specific Caddy version for binary mode | latest |

Examples:

```bash
bash install_caddy.sh binary
bash install_caddy.sh binary --enable-static-site --editor hx
bash install_caddy.sh docker --docker-root ~/projects/caddy-gateway
```

After installation, open a new shell or run:

```bash
exec $SHELL -l
```

## Commands

Load the wrapper in bash:

```bash
source /etc/caddy/.bash_caddy
```

For Docker mode, source the deployed helper instead:

```bash
source <docker-root>/.bash_caddy
```

The helper now registers completion for both bash and zsh. In zsh, no manual `bashcompinit` setup is required after the updated helper is deployed.

Common commands:

```bash
caddy up
caddy down
caddy restart
caddy reload
caddy status
caddy edit
caddy version
caddy logs runtime
caddy logs runtime -f
caddy logs access
caddy logs access -f
caddy fmt
caddy validate
```

`caddy version` now prints deployment details before the upstream version line, including:

- active mode
- install root and config paths
- log and state directories
- helper script and helper env paths
- static site status
- generated files and directories with `present` or `missing` status

## Logs

- `runtime.log`: Caddy runtime events such as startup, reload, ACME certificate issuance, renewal, and internal warnings/errors.
- `access.log`: HTTP request logs such as client IP, method, path, status, and response details.

## Permissions

- Binary mode needs root or a sudo-capable user because it writes under `/usr/local/bin`, `/etc/caddy`, and `/etc/systemd/system`.
- Docker mode writes only under the selected docker root, so it typically runs as the current user.

## Validation

```bash
cd bitfennec_simple_page/http/linux/caddy
bash tests/test_install_caddy.sh
```