ZKAccess C3 dashboard bundle — README

This repository runs a small Python (FastAPI) service that will eventually talk to a ZKAccess C3-100 over the network (Pull SDK–style TCP, typically port 4370). Today it ships a LAN web dashboard and JSON status endpoints, packaged with Docker Compose for Linux (setup-ubuntu-server.sh) or Windows (setup-windows.bat + Docker Desktop).

1. What you edit vs what Docker runs

What	Where it lives	Who reads it
All runtime settings (panel IP, ports, passwords, public URL)	`.env` in the project root (next to `docker-compose.yml`)	Docker Compose injects `C3_` and `DASHBOARD_PUBLIC_BASE_URL` into the container; the app also reads `.env`* when present (see `app/settings.py`).
Which host TCP port the dashboard listens on from outside the container	`.env` → `DASHBOARD_HOST_PORT`	Only `docker-compose.yml` (the `ports:` mapping). This value is not required inside the app if you set `DASHBOARD_PUBLIC_BASE_URL` correctly.
Optional second host port	`.env` → `DASHBOARD_HOST_PORT_ALT` and you must uncomment the second `ports:` line	`docker-compose.yml`
Image / service name	`Dockerfile`, `docker-compose.yml`	You normally do not change these unless you rename the service.

Rule of thumb: to “replace all settings,” edit only .env (and rarely uncomment a port line in docker-compose.yml). Then recreate the container so new environment values apply.

Security: keep your real .env file out of git (it is listed in .gitignore). Never paste real passwords into issues or screenshots without redacting.

2. Prerequisites

A PC running Ubuntu, Linux Mint, or Debian on the same LAN as the C3-100.
Internet access on first run if Docker must be installed (the script downloads Docker’s official install script).
sudo privileges (Docker install, optional UFW, and Docker commands until your user is in the docker group).
bash, curl, and python3 (for the interactive wizard’s safe .env writer; curl is installed automatically if missing and apt-get exists).

The bootstrap script can install Docker for you on apt-based distros. If you install Docker yourself first, see:

docker --version
docker compose version

3. One script on Ubuntu (recommended)

From the repository root (the folder that contains docker-compose.yml and setup-ubuntu-server.sh):

cd /path/to/del-hy-prnhs
bash setup-ubuntu-server.sh

What the script does, in order

cd to the repo root (next to the script).
Docker
- If docker and docker compose are missing on Ubuntu / Debian / Linux Mint / Pop!_OS (ID in /etc/os-release), it asks Install Docker Engine now? [Y/n] and, if you accept, runs Docker’s official get.docker.com script with sudo (installs Engine + Compose plugin). It installs curl via apt-get first if needed.
- On other distributions it stops with a link to the manual Docker install docs.
- After install it runs sudo usermod -aG docker "$USER" and reminds you to log out and back in (or newgrp docker). Until then, the script uses sudo docker compose when your user cannot talk to the daemon.
.env (interactive wizard) — unless .env already exists and you answer no to reconfigure:
- Panel IP / hostname
- Panel TCP port (default 4370)
- Username (optional)
- Password / comm key (optional, hidden; confirm once)
- Dashboard port on this server (default 8080)
- Public base URL for bookmarks (default http://<detected-LAN-IP>:<dashboard-port>)
- Confirm Write to .env — file is written with mode 600 and double-quoted values where needed.
docker compose up -d --build — starts the stack.
--ufw only: after a successful start, sudo ufw allow <DASHBOARD_HOST_PORT>/tcp and ufw reload.

Script options

Command	Meaning
`bash setup-ubuntu-server.sh`	Install Docker if missing (with prompt), then wizard / existing `.env`, then compose up.
`bash setup-ubuntu-server.sh --ufw`	Same, plus UFW rule for the dashboard port after compose succeeds.
`bash setup-ubuntu-server.sh --force-recreate`	Pass `--force-recreate` to compose (e.g. after manual `.env` edits).
`bash setup-ubuntu-server.sh --non-interactive` or `-y`	No Docker install prompt, no wizard — requires an existing `.env`. Use on repeat runs in automation.
`bash setup-ubuntu-server.sh --help`	Short usage.

Typical flows

Fresh server: bash setup-ubuntu-server.sh → accept Docker install → answer wizard → open the printed URL. Use --ufw if you want the firewall opened automatically.
Change panel or password later: run the script again and answer y to reconfigure, or edit .env by hand and run bash setup-ubuntu-server.sh --force-recreate.

You can chmod +x setup-ubuntu-server.sh and run ./setup-ubuntu-server.sh; bash setup-ubuntu-server.sh works without that.

Security note: the Docker install script is upstream-maintained but still runs as root; only use on machines where that is acceptable. Review Docker’s install documentation if you prefer a manual apt-based install instead.

3.1 Windows (Docker Desktop)

Install Docker Desktop for Windows (includes Compose v2). From a Command Prompt or PowerShell, cd to the repo folder that contains docker-compose.yml:

cd C:\path\to\del-hy-prnhs
setup-windows.bat

setup-windows.bat checks docker / docker compose, runs setup-windows-wizard.ps1 when .env is missing (or when you choose to reconfigure), then docker compose up -d --build.
The wizard asks for the same values as the Linux script (C3 IP, port, optional user/password, dashboard port, public URL) and writes .env with UTF-8 (password prompts use masked input).
HTTP is still Uvicorn + FastAPI inside the container (Dockerfile, app\main.py); Docker Desktop publishes DASHBOARD_HOST_PORT → 8000 (see docker-compose.yml).

Command	Meaning
`setup-windows.bat`	Wizard if needed, then compose up.
`setup-windows.bat /q`	No prompts; use existing `.env` (or copy `.env.example` once if missing).
`setup-windows.bat /r`	Pass `--force-recreate` to compose (can combine: `/q /r`).
`setup-windows.bat /h`	Help.

If other PCs cannot reach the dashboard, allow the port in Windows Defender Firewall (Docker Desktop often prompts the first time).

4. First-time install (manual, step by step)

Use this if you prefer not to use the script. Run everything from the project directory.

4.1 Create your `.env` from the template

cd /path/to/del-hy-prnhs
cp .env.example .env

4.2 Edit `.env` and replace every value

nano .env
# or: vim .env   or open .env in your desktop editor

Variable	Set it to…
`C3_HOST`	The IPv4 address (or DNS name) of your C3-100 on the LAN.
`C3_PORT`	Usually `4370`. Change only if the device uses another TCP port.
`C3_USERNAME`	Optional. Leave empty if the panel only uses a password / comm key.
`C3_PASSWORD`	The panel password or comm key if required; leave empty if not used.
`DASHBOARD_HOST_PORT`	Any free TCP port on the Linux host (e.g. `8080`). Browser: `http://<server-ip>:<port>/`.
`DASHBOARD_PUBLIC_BASE_URL`	Same service as a full URL, e.g. `http://192.168.1.50:8080` — host and port must match `DASHBOARD_HOST_PORT`.

Optional second port: set DASHBOARD_HOST_PORT_ALT in .env, then in docker-compose.yml uncomment the second ports: line. Use two different port numbers.

4.3 Open the firewall (if UFW is enabled)

sudo ufw allow <DASHBOARD_HOST_PORT>/tcp comment 'ZKAccess dashboard'
sudo ufw reload

4.4 Build and start the stack

docker compose up -d --build

4.5 Verify

docker compose ps
docker compose logs --tail=50 dashboard
curl -sS "http://127.0.0.1:<DASHBOARD_HOST_PORT>/health"
curl -sS "http://127.0.0.1:<DASHBOARD_HOST_PORT>/api/status"

On another PC: http://<linux-server-ip>:<DASHBOARD_HOST_PORT>/ — /api/status never returns C3_PASSWORD.

5. How to change settings later (replace / update)

Edit .env.
Apply changes:
```
docker compose up -d --force-recreate
```
If code or requirements.txt / Dockerfile changed:
```
docker compose up -d --build --force-recreate
```
Or use: bash setup-ubuntu-server.sh --force-recreate
If DASHBOARD_HOST_PORT changed, update UFW (or run bash setup-ubuntu-server.sh --ufw --force-recreate after editing .env).

6. Day-to-day commands (project directory)

Goal	Command
Start	`docker compose up -d`
Rebuild	`docker compose up -d --build`
Apply only `.env` changes	`docker compose up -d --force-recreate`
Logs	`docker compose logs -f dashboard`
Stop	`docker compose down`

7. Full list of environment variables

Variable	Required	Default (if unset)	Purpose
`C3_HOST`	Strongly recommended	empty	ZKAccess panel IP or hostname.
`C3_PORT`	No	`4370`	Panel TCP port.
`C3_USERNAME`	No	empty	Optional; reserved for setups that need a user name.
`C3_PASSWORD`	Depends on panel	empty	Panel password / comm key; never returned by `/api/status`.
`DASHBOARD_HOST_PORT`	No (Compose default)	`8080` in `docker-compose.yml`	Host port for the web UI.
`DASHBOARD_HOST_PORT_ALT`	No	only if line uncommented in compose	Second host port to the same app.
`DASHBOARD_PUBLIC_BASE_URL`	No	empty	Bookmark URL on the HTML dashboard.

Compose reads .env for ${...} interpolation in docker-compose.yml.

Library note: zkaccess-c3-py often uses connect(password=...) only; C3_USERNAME is still available for your firmware or future code paths.

8. Router port forwarding (optional)

Forward WAN TCP to <LAN-ip-of-linux-PC>:<DASHBOARD_HOST_PORT>. The app does not need the WAN port in .env. For internet exposure, prefer VPN or HTTPS + authentication.

9. Running without Docker (developers only)

cd /path/to/del-hy-prnhs
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

Open http://<this-pc-ip>:8000/. Without Docker, DASHBOARD_HOST_PORT is ignored; you pick the port on the uvicorn line.

10. Troubleshooting

Symptom	Things to check
`curl` to `127.0.0.1:PORT` fails	`docker compose ps`; `docker compose logs dashboard`; `PORT` vs `DASHBOARD_HOST_PORT` in `.env`.
Other PCs cannot connect	Subnet, AP isolation, UFW, correct server IP.
Old values after editing `.env`	`docker compose up -d --force-recreate` or `bash setup-ubuntu-server.sh --force-recreate`.
Docker permission denied	User in `docker` group, re-login, or `sudo` (not ideal long-term).

11. Project background

plan.md — architecture, C3 data model, phases.
zkaccess-c3-py — Python library for the panel protocol (integration planned in later phases).

12. Template file reference

The checked-in .env.example lists all keys. When in doubt:

cp .env.example .env

Then edit .env only. After changes: docker compose up -d --force-recreate (or bash setup-ubuntu-server.sh --force-recreate) and add --build when code or dependencies change.

Test

Contents

ZKAccess C3 dashboard bundle — README

1. What you edit vs what Docker runs

2. Prerequisites

3. One script on Ubuntu (recommended)

What the script does, in order

Script options

Typical flows

3.1 Windows (Docker Desktop)

4. First-time install (manual, step by step)

4.1 Create your `.env` from the template

4.2 Edit `.env` and replace every value

4.3 Open the firewall (if UFW is enabled)

4.4 Build and start the stack

4.5 Verify

5. How to change settings later (replace / update)

6. Day-to-day commands (project directory)

7. Full list of environment variables

8. Router port forwarding (optional)

9. Running without Docker (developers only)

10. Troubleshooting

11. Project background

12. Template file reference

Navigation menu

Test

ZKAccess C3 dashboard bundle — README

1. What you edit vs what Docker runs

2. Prerequisites

3. One script on Ubuntu (recommended)

What the script does, in order

Script options

Typical flows

3.1 Windows (Docker Desktop)

4. First-time install (manual, step by step)

4.1 Create your .env from the template

4.2 Edit .env and replace every value

4.3 Open the firewall (if UFW is enabled)

4.4 Build and start the stack

4.5 Verify

5. How to change settings later (replace / update)

6. Day-to-day commands (project directory)

7. Full list of environment variables

8. Router port forwarding (optional)

9. Running without Docker (developers only)

10. Troubleshooting

11. Project background

12. Template file reference

Navigation menu

Search

4.1 Create your `.env` from the template

4.2 Edit `.env` and replace every value