Samikciku: Imported from Markdown

2026-08-22T23:48:18Z

Imported from Markdown

New page

= 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''' (<code>setup-ubuntu-server.sh</code>) or '''Windows''' (<code>setup-windows.bat</code> + Docker Desktop).

-----


== 1. What you edit vs what Docker runs ==

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

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

'''Security:''' keep your real <code>.env</code> file out of git (it is listed in <code>.gitignore</code>). 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).
* '''<code>sudo</code>''' privileges (Docker install, optional UFW, and Docker commands until your user is in the <code>docker</code> group).
* '''<code>bash</code>''', '''<code>curl</code>''', and '''<code>python3</code>''' (for the interactive wizard’s safe <code>.env</code> writer; <code>curl</code> is installed automatically if missing and <code>apt-get</code> exists).

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

<syntaxhighlight lang="bash">docker --version
docker compose version</syntaxhighlight>

-----


== 3. One script on Ubuntu (recommended) ==

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

<syntaxhighlight lang="bash">cd /path/to/del-hy-prnhs
bash setup-ubuntu-server.sh</syntaxhighlight>

=== What the script does, in order ===

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


=== Script options ===

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


=== Typical flows ===

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

You can '''<code>chmod +x setup-ubuntu-server.sh</code>''' and run '''<code>./setup-ubuntu-server.sh</code>'''; '''<code>bash setup-ubuntu-server.sh</code>''' 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 [https://docs.docker.com/engine/install/ubuntu/ Docker’s install documentation] if you prefer a manual apt-based install instead.


=== 3.1 Windows (Docker Desktop) ===

Install '''[https://docs.docker.com/desktop/install/windows-install/ Docker Desktop for Windows]''' (includes Compose v2). From a '''Command Prompt''' or '''PowerShell''', <code>cd</code> to the repo folder that contains <code>docker-compose.yml</code>:

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

{| class="wikitable"
|-
! Command
! Meaning
|-
| <code>setup-windows.bat</code>
| Wizard if needed, then compose up.
|-
| <code>setup-windows.bat /q</code>
| No prompts; use existing <code>.env</code> (or copy <code>.env.example</code> once if missing).
|-
| <code>setup-windows.bat /r</code>
| Pass '''<code>--force-recreate</code>''' to compose (can combine: <code>/q /r</code>).
|-
| <code>setup-windows.bat /h</code>
| 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 <code>.env</code> from the template ===

<syntaxhighlight lang="bash">cd /path/to/del-hy-prnhs
cp .env.example .env</syntaxhighlight>

=== 4.2 Edit <code>.env</code> and replace every value ===

<syntaxhighlight lang="bash">nano .env
# or: vim .env or open .env in your desktop editor</syntaxhighlight>
{| class="wikitable"
|-
! Variable
! Set it to…
|-
| <code>C3_HOST</code>
| The '''IPv4 address''' (or DNS name) of your '''C3-100''' on the LAN.
|-
| <code>C3_PORT</code>
| Usually '''<code>4370</code>'''. Change only if the device uses another TCP port.
|-
| <code>C3_USERNAME</code>
| '''Optional.''' Leave empty if the panel only uses a password / comm key.
|-
| <code>C3_PASSWORD</code>
| The panel '''password or comm key''' if required; leave empty if not used.
|-
| <code>DASHBOARD_HOST_PORT</code>
| Any '''free TCP port on the Linux host''' (e.g. <code>8080</code>). Browser: <code>http://<server-ip>:<port>/</code>.
|-
| <code>DASHBOARD_PUBLIC_BASE_URL</code>
| Same service as a full URL, e.g. <code>http://192.168.1.50:8080</code> — '''host and port''' must match <code>DASHBOARD_HOST_PORT</code>.
|}

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


=== 4.3 Open the firewall (if UFW is enabled) ===

<syntaxhighlight lang="bash">sudo ufw allow <DASHBOARD_HOST_PORT>/tcp comment 'ZKAccess dashboard'
sudo ufw reload</syntaxhighlight>

=== 4.4 Build and start the stack ===

<syntaxhighlight lang="bash">docker compose up -d --build</syntaxhighlight>

=== 4.5 Verify ===

<syntaxhighlight lang="bash">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"</syntaxhighlight>
On another PC: <code>http://<linux-server-ip>:<DASHBOARD_HOST_PORT>/</code> — <code>/api/status</code> never returns <code>C3_PASSWORD</code>.

-----


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

<ol style="list-style-type: decimal;">
<li>'''Edit''' <code>.env</code>.</li>
<li>Apply changes:
<syntaxhighlight lang="bash">docker compose up -d --force-recreate</syntaxhighlight>
If '''code''' or '''<code>requirements.txt</code>''' / '''<code>Dockerfile</code>''' changed:
<syntaxhighlight lang="bash">docker compose up -d --build --force-recreate</syntaxhighlight>
Or use: '''<code>bash setup-ubuntu-server.sh --force-recreate</code>'''</li>
<li>If '''<code>DASHBOARD_HOST_PORT</code>''' changed, update '''UFW''' (or run '''<code>bash setup-ubuntu-server.sh --ufw --force-recreate</code>''' after editing <code>.env</code>).</li></ol>

-----


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

{| class="wikitable"
|-
! Goal
! Command
|-
| Start
| <code>docker compose up -d</code>
|-
| Rebuild
| <code>docker compose up -d --build</code>
|-
| Apply '''only''' <code>.env</code> changes
| <code>docker compose up -d --force-recreate</code>
|-
| Logs
| <code>docker compose logs -f dashboard</code>
|-
| Stop
| <code>docker compose down</code>
|}

-----


== 7. Full list of environment variables ==

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

Compose reads <code>.env</code> for <code>${...}</code> interpolation in <code>docker-compose.yml</code>.

'''Library note:''' [https://github.com/vwout/zkaccess-c3-py zkaccess-c3-py] often uses '''<code>connect(password=...)</code>''' only; <code>C3_USERNAME</code> is still available for your firmware or future code paths.

-----


== 8. Router port forwarding (optional) ==

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

-----


== 9. Running without Docker (developers only) ==

<syntaxhighlight lang="bash">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</syntaxhighlight>
Open <code>http://<this-pc-ip>:8000/</code>. Without Docker, <code>DASHBOARD_HOST_PORT</code> is ignored; you pick the port on the <code>uvicorn</code> line.

-----


== 10. Troubleshooting ==

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

-----


== 11. Project background ==

* '''[[plan.md]]''' — architecture, C3 data model, phases.
* '''[https://github.com/vwout/zkaccess-c3-py zkaccess-c3-py]''' — Python library for the panel protocol (integration planned in later phases).

-----


== 12. Template file reference ==

The checked-in '''<code>.env.example</code>''' lists all keys. When in doubt:

<syntaxhighlight lang="bash">cp .env.example .env</syntaxhighlight>
Then edit '''<code>.env</code>''' only. After changes: '''<code>docker compose up -d --force-recreate</code>''' (or '''<code>bash setup-ubuntu-server.sh --force-recreate</code>''') and add '''<code>--build</code>''' when code or dependencies change.

Test - Revision history

Samikciku: Imported from Markdown