241 lines
9.5 KiB
Markdown
241 lines
9.5 KiB
Markdown
|
|
|
|
# Lagomare Gates
|
|
|
|
A web-based gate access management and control system. Authorized users can remotely open physical car and pedestrian gates via a mobile-friendly PWA. An admin dashboard provides full management of gates, access codes, and users.
|
|
|
|
## Features
|
|
|
|
- **Keypass authentication** — users authenticate with an access code; each keypass can have a per-gate allowlist and an optional expiration date
|
|
- **Remote gate control** — integrates with [AVConnect](https://www.avconnect.it) to trigger gate macros
|
|
- **Role-based admin panel** — two roles (`admin`, `manager`) with different permission levels
|
|
- **Access audit log** — every open attempt is logged with timestamp, keypass, gate, IP, and result; filterable and paginated
|
|
- **Keypass QR codes** — generate a scannable QR code for each keypass; scanning opens the PWA and logs in automatically
|
|
- **Keypass code options** — choose character set (alphanumeric, alpha, numeric, or a 4-word passphrase) and length when auto-generating codes
|
|
- **Telegram notifications** — optional push notifications to a Telegram group whenever a gate is opened
|
|
- **Progressive Web App** — installable on mobile devices with offline caching
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| Backend | FastAPI + Uvicorn |
|
|
| ORM | SQLAlchemy |
|
|
| Database | SQLite |
|
|
| Auth | JWT (HS256) + bcrypt |
|
|
| Credential storage | Fernet symmetric encryption |
|
|
| Gate integration | AVConnect HTTP API |
|
|
| Notifications | Telegram Bot API |
|
|
| QR generation | qrcode + Pillow |
|
|
| Frontend | Vanilla JS PWA |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── main.py # App entry point, startup, static file serving
|
|
├── core/
|
|
│ ├── auth.py # JWT creation/verification, password hashing
|
|
│ ├── config.py # Settings loaded from environment variables
|
|
│ ├── database.py # SQLAlchemy models and DB initialization
|
|
│ ├── dependencies.py # FastAPI dependency injection (auth guards)
|
|
│ └── schemas.py # Pydantic request/response schemas
|
|
├── routers/
|
|
│ ├── auth.py # POST /api/auth/admin, POST /api/auth/keypass
|
|
│ ├── gates.py # User-facing gate list and open endpoints
|
|
│ ├── keypasses.py # Admin keypass CRUD + QR code generation
|
|
│ ├── admins.py # Admin user management
|
|
│ ├── credentials.py # AVConnect credential management
|
|
│ ├── stats.py # Access log / statistics (paginated, filtered)
|
|
│ └── telegram.py # Telegram notification configuration
|
|
├── services/
|
|
│ ├── avconnect.py # AVConnect session management and macro execution
|
|
│ ├── gates.py # Gate open orchestration
|
|
│ └── telegram.py # Telegram Bot API client
|
|
└── static/ # Frontend PWA (index.html, admin.html, JS, CSS)
|
|
data/
|
|
└── gates.db # SQLite database (auto-created on first run)
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| POST | `/api/auth/admin` | Admin login — returns JWT |
|
|
| POST | `/api/auth/keypass` | Keypass login — returns JWT |
|
|
|
|
### User (keypass token required)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/gates` | List gates accessible to the authenticated keypass |
|
|
| POST | `/api/gates/{gate_id}/open` | Open a gate |
|
|
|
|
### Admin — Gates (manager+)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/gates` | List all gates |
|
|
| POST | `/api/admin/gates` | Create a gate *(admin only)* |
|
|
| PUT | `/api/admin/gates/{gate_id}` | Update a gate *(admin only)* |
|
|
| DELETE | `/api/admin/gates/{gate_id}` | Delete a gate *(admin only)* |
|
|
| POST | `/api/admin/gates/{gate_id}/open` | Manually open a gate |
|
|
|
|
### Admin — Keypasses (manager+)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/keypasses` | List all keypasses |
|
|
| POST | `/api/admin/keypasses` | Create a keypass |
|
|
| PATCH | `/api/admin/keypasses/{kp_id}` | Update a keypass |
|
|
| DELETE | `/api/admin/keypasses/{kp_id}` | Revoke a keypass |
|
|
| GET | `/api/admin/keypasses/{kp_id}/qr` | Download QR code PNG for a keypass |
|
|
|
|
### Admin — Users (admin only)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/admins` | List admin users |
|
|
| POST | `/api/admin/admins` | Create an admin user |
|
|
| DELETE | `/api/admin/admins/{username}` | Delete an admin user |
|
|
| PATCH | `/api/admin/admins/{username}/password` | Change password |
|
|
|
|
### Admin — AVConnect Credentials (admin only)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/credentials` | View stored credentials |
|
|
| PUT | `/api/admin/credentials` | Create or update credentials |
|
|
| GET | `/api/admin/credentials/mock` | Get mock mode status |
|
|
| PUT | `/api/admin/credentials/mock` | Enable or disable mock mode |
|
|
|
|
### Admin — Statistics (manager+)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/stats` | Paginated, filtered access log |
|
|
|
|
Query parameters: `gate_id`, `keypass_code` (partial match), `success` (bool), `date_from`, `date_to`, `page` (default 1), `page_size` (default 50, max 200).
|
|
|
|
### Admin — Telegram Notifications (admin only)
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| GET | `/api/admin/telegram` | Get current Telegram configuration |
|
|
| PUT | `/api/admin/telegram` | Save bot token and chat ID |
|
|
| POST | `/api/admin/telegram/test` | Send a test message |
|
|
|
|
## Configuration
|
|
|
|
All settings are read from environment variables (centralised in `src/core/config.py`).
|
|
|
|
### Security
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `SECRET_KEY` | *(required)* | JWT signing key and Fernet encryption key. The application will refuse to start if this is not set. Use a long random string (`openssl rand -hex 32`). |
|
|
|
|
### Admin seed account
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `ADMIN_USERNAME` | `admin` | Username for the initial admin account created on first run. |
|
|
| `ADMIN_PASSWORD` | *(none)* | Password for the initial admin account. If unset, no seed account is created. Minimum 12 characters. |
|
|
|
|
### Server
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `APP_PORT` | `8000` | HTTP port the server listens on. |
|
|
|
|
### Database
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `DATABASE_URL` | `sqlite:///data/gates.db` | SQLAlchemy database URL. |
|
|
|
|
### Network / reverse proxy
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `CORS_ORIGINS` | *(empty — no cross-origin requests)* | Comma-separated list of allowed CORS origins, e.g. `https://gates.example.com`. |
|
|
| `TRUSTED_PROXY_IPS` | `127.0.0.1` | Comma-separated list of reverse-proxy IPs whose `X-Forwarded-For` header is trusted for client IP resolution. |
|
|
|
|
### Logging
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `LOG_LEVEL` | `INFO` | Logging verbosity. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
|
|
| `LOG_FILE` | `/var/log/lagomaregates.log` | Path to the rotating log file (10 MB, 5 backups). Set to an empty string to disable file logging. |
|
|
|
|
## Running with Docker Compose
|
|
|
|
```bash
|
|
# Copy and edit the compose file to set your SECRET_KEY
|
|
docker compose up -d
|
|
```
|
|
|
|
The default `docker-compose.yml` starts the service on port `8000`. Set a strong `SECRET_KEY` and, optionally, `ADMIN_USERNAME` / `ADMIN_PASSWORD` before deploying.
|
|
|
|
The `./data` directory is mounted into the container so the SQLite database persists across restarts.
|
|
|
|
## Running Locally
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
export SECRET_KEY="$(openssl rand -hex 32)"
|
|
export ADMIN_USERNAME="admin"
|
|
export ADMIN_PASSWORD="changeme-at-least-12"
|
|
|
|
uvicorn src.main:app --port 8000
|
|
```
|
|
|
|
The application is then available at:
|
|
|
|
- **User interface** — `http://localhost:8000/`
|
|
- **Admin dashboard** — `http://localhost:8000/admin`
|
|
|
|
## AVConnect Integration
|
|
|
|
Gates are controlled through the AVConnect platform. Each gate is mapped to an AVConnect *macro ID*. When a gate open request is received, the service:
|
|
|
|
1. Authenticates with AVConnect using the stored credentials (session is cached in the database)
|
|
2. Executes the configured macro for the gate
|
|
|
|
Credentials (password) are stored encrypted in the database using Fernet symmetric encryption derived from `SECRET_KEY`.
|
|
|
|
**Mock mode** — when enabled via the admin dashboard, gate open requests always succeed without contacting AVConnect. Useful for testing.
|
|
|
|
## Keypass QR Codes
|
|
|
|
Each active keypass has a **QR** button in the admin panel. Clicking it generates a PNG QR code that encodes the URL:
|
|
|
|
```
|
|
https://<your-domain>/?k=<KEYPASS_CODE>
|
|
```
|
|
|
|
Scanning the code with a phone opens the web app and logs in automatically. If the keypass is expired or revoked, the user is shown an error on the login screen.
|
|
|
|
## Telegram Notifications
|
|
|
|
Configure a Telegram bot to receive a message in a group or chat every time a gate is opened:
|
|
|
|
1. Create a bot via [@BotFather](https://t.me/BotFather) and copy the token
|
|
2. Add the bot to your group and obtain the chat ID (e.g. using [@userinfobot](https://t.me/userinfobot))
|
|
3. Open **Admin → Notifications**, enter the token and chat ID, and click **Save**
|
|
4. Use **Send test message** to verify the setup
|
|
|
|
Notifications are sent in a background thread and never block the gate open response. Failures are logged as warnings and do not affect gate operation.
|
|
|
|
## Roles
|
|
|
|
| Role | Permissions |
|
|
|---|---|
|
|
| `admin` | Full access — all endpoints including gate/user/credential/notification management |
|
|
| `manager` | Gate open, keypass management, statistics — cannot manage admin users, AVConnect credentials, gate configuration, or Telegram settings |
|