mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-23 06:40:53 -05:00
Dries Peeters
e34a668ddc
Introduce AUTH_METHOD values ldap and all, with LDAP_* environment settings, ldap3-based LDAPService (search, optional groupOfNames checks, user bind, DB sync), and users.auth_provider (local|oidc|ldap) via migration 153_add_user_auth_provider. Login supports LDAP-only and combined all (local then LDAP where appropriate); OIDC callback sets auth_provider. Forgot/reset/change password flows skip LDAP-managed accounts. Admin System Settings gains a read-only LDAP summary and POST /admin/ldap/test. Production env validation requires core LDAP variables when LDAP is enabled; OIDC registration and docs recognize all. Documentation: new docs/admin/configuration/LDAP_SETUP.md; updates to OIDC_SETUP, GETTING_STARTED, Docker guides, Render deploy notes, docs README, and CHANGELOG. Tests: tests/test_ldap_auth.py; test_oidc_logout allows auth_method all.
84 lines
5.9 KiB
Markdown
84 lines
5.9 KiB
Markdown
# Deploy TimeTracker on Render
|
||
|
||
This guide explains how to host TimeTracker as a Web Service on [Render](https://render.com) with optional **demo mode** (single user, credentials shown on the login page).
|
||
|
||
The Blueprint uses the **pre-built Docker image** from GitHub Container Registry (`ghcr.io/drytrix/timetracker:latest`), i.e. the same image built by your GitHub Actions (cd-release / cd-development). No Python or npm build runs on Render.
|
||
|
||
## Prerequisites
|
||
|
||
- A [Render](https://render.com) account
|
||
- This repository connected to your GitHub (or GitLab) account
|
||
- Docker image published to GHCR (e.g. by pushing to `main` or creating a release so the CD workflow builds and pushes the image)
|
||
|
||
## Deploy with the Blueprint
|
||
|
||
1. In the Render Dashboard, click **New** → **Blueprint**.
|
||
2. Connect your Git provider and select the TimeTracker repository.
|
||
3. Render will detect the `render.yaml` in the repository root.
|
||
4. Review the blueprint: it creates one **PostgreSQL** database and one **Web Service** that pulls `ghcr.io/drytrix/timetracker:latest`.
|
||
5. Click **Apply** to create the database and deploy the app.
|
||
|
||
To deploy a new version, push to `main` or create a release so GitHub Actions builds and pushes a new image, then in Render trigger a **Manual Deploy** (or use a deploy hook) to pull the updated image.
|
||
|
||
### Automatic demo deploy via release workflow
|
||
|
||
If you host a demo site on Render, the release workflow can automatically trigger a redeploy when a new container is published. Configure:
|
||
|
||
1. In Render: open your demo Web Service → **Settings** → **Deploy Hook** and copy the deploy hook URL.
|
||
2. In GitHub: add an **organization secret** named `TimeTrackerDemoRender` with the deploy hook URL as the value. Grant your TimeTracker repository access to this secret (Organization Settings → Secrets and variables → Actions → Repository access).
|
||
3. On each release (push to `main`, tag, or manual dispatch), after the Docker image is built and pushed, the workflow sends a POST request to the deploy hook. Render will pull the new image and redeploy your demo site.
|
||
|
||
If the secret is not set, the workflow skips the deploy trigger and the release completes normally.
|
||
|
||
## Environment variables
|
||
|
||
The blueprint sets:
|
||
|
||
- **FLASK_ENV**: `production`
|
||
- **FLASK_APP**: `app:create_app()` (used for `flask db upgrade` in the pre-deploy step)
|
||
- **SECRET_KEY**: Auto-generated by Render (recommended; you can override in the Dashboard)
|
||
- **DATABASE_URL**: Filled automatically from the linked PostgreSQL database
|
||
- **AUTH_METHOD**: `local` (default), or `none` | `oidc` | `ldap` | `both` | `all` — see `env.example` and [LDAP Setup](../admin/configuration/LDAP_SETUP.md) / [OIDC Setup](../admin/configuration/OIDC_SETUP.md)
|
||
- **REDIS_ENABLED**: `false` (rate limiting uses in-memory storage; no Redis required for demo)
|
||
|
||
## Demo mode (single-user demo)
|
||
|
||
To run a **demo** instance where only one user can log in and the credentials are shown on the login page:
|
||
|
||
1. In the Render Dashboard, open your **timetracker** web service.
|
||
2. Go to **Environment** and add (or uncomment in `render.yaml` and redeploy):
|
||
- **DEMO_MODE**: `true`
|
||
- **DEMO_USERNAME**: `demo` (or any username you want)
|
||
- **DEMO_PASSWORD**: Set a strong password (use a **Secret** so it is not visible in the dashboard to others)
|
||
3. Redeploy the service.
|
||
|
||
In demo mode:
|
||
|
||
- Only the user with **DEMO_USERNAME** can log in.
|
||
- The login page shows the demo username and password.
|
||
- Self-registration and admin user creation are disabled; OIDC cannot create new users.
|
||
- The demo user is created automatically on first run if it does not exist.
|
||
- The demo account has the standard **user** role only (not an administrator), so settings, PDF layout editing, and similar admin routes are unavailable on the demo login.
|
||
|
||
**Security:** Use a strong **DEMO_PASSWORD** for any public demo. Do not use `DEMO_MODE=true` for production multi-user deployments.
|
||
|
||
**Upgrading older demos:** If your database was created before this change and the demo user still has admin access, redeploying a current image runs a one-time adjustment on startup: the demo user is moved to the **user** role and `admin` / `super_admin` RBAC roles are removed. If you disabled `DEMO_MODE` and need a real administrator, create one via CLI or temporarily disable demo mode and use `ADMIN_USERNAMES` as documented in the main README.
|
||
|
||
## Optional: Run without the Blueprint
|
||
|
||
If you prefer to create the database and web service manually:
|
||
|
||
1. Create a **PostgreSQL** database and note the **Internal Database URL** (or **External** if your app runs elsewhere).
|
||
2. Create a **Web Service** and choose **Deploy an existing image from a registry**.
|
||
- **Image URL**: `ghcr.io/drytrix/timetracker:latest`
|
||
- **Docker Command**: `gunicorn --bind 0.0.0.0:$PORT --worker-class eventlet --workers 1 --timeout 120 "app:create_app()"`
|
||
- **Pre-deploy Command**: `flask db upgrade`
|
||
- If the image is private, add GHCR registry credentials in Render (Settings → Registry).
|
||
3. In **Environment**, set **FLASK_APP** to `app:create_app()`, **DATABASE_URL** to the Postgres URL, **SECRET_KEY**, and any demo-mode variables as above.
|
||
|
||
## Troubleshooting
|
||
|
||
- **Migrations**: The pre-deploy command runs `flask db upgrade`. If it fails, check that **FLASK_APP** is set to `app:create_app()` and that **DATABASE_URL** is set and reachable from Render.
|
||
- **Image**: The Blueprint uses the pre-built image `ghcr.io/drytrix/timetracker:latest`. Ensure that image exists (trigger a build by pushing to `main` or running the release workflow). If the image is private, add GitHub Container Registry credentials in Render Dashboard → Settings → Registry.
|
||
- **Database URL**: Render’s PostgreSQL URL is usually in `postgres://` form; the app uses `postgresql+psycopg2`. If you see connection errors, try setting **DATABASE_URL** to the same URL with the scheme changed to `postgresql://` (Render may also provide a direct URL in the database dashboard).
|