Skip to content
jandaroscherPublic

About

CiviDash – open-source sustainability dashboard for municipalities (Laravel, Filament, Vue). Mirror of openCode.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

550 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CiviDash

CiviDash is an open-source sustainability dashboard for municipalities, built on Laravel (backend/admin via Filament) and Vue 3 (frontend). It supports multi-tenancy (multiple dashboards/tenants) and multilingual content (German/English), with KPI tiles, filtering, full-text search, a Filament-based page builder and data import. The related CIVITAS/CORE add-on is maintained separately.

Where to start

  • Editors and admins in the municipal administration: the admin panel of a running dashboard is at /admin on its domain, e.g. https://dashboard.example.org/admin. If you do not know the domain, ask whoever runs your dashboard. Sign in with email and password, or with Sign in with Keycloak (German: Mit Keycloak anmelden) where single sign-on is set up; some installations offer only the Keycloak button. The user guide (German / English) explains the panel step by step, starting with login and interface (German / English).
  • Getting access: an admin of the dashboard creates your account. With Keycloak, whoever manages your Keycloak or CIVITAS/CORE accounts grants access, and the account is created at your first sign-in.
  • Operators who install and run CiviDash: start with the admin guide. It covers deployment and how to create the first admin account.
  • Developers: see Quickstart and the developer guide.

Features

  • KPI tiles with time series
  • Filtering by category groups
  • Full-text search
  • Multilingual content (German/English)
  • Multi-dashboard / multi-tenancy
  • Filament admin with page builder
  • Data import (JSON bundles) and export (JSON/CSV)
  • CIVITAS/CORE integration

Tech stack

Layer Technology
Backend Laravel 12, PHP 8.2, Sanctum
Admin Filament 3.3, Filament Fabricator
Frontend Vue 3, Vue Router 4, Pinia
Styling Tailwind CSS 4
Build Vite 6
Database PostgreSQL 16
Testing PHPUnit, Vitest, Playwright

Quickstart

Local development runs through DDEV. Node.js 22 or newer is required outside of DDEV (e.g. for editor tooling); see .nvmrc (nvm use).

ddev start                              # Start environment
ddev exec composer install              # Install PHP dependencies
ddev exec php artisan key:generate      # Generate app key (DDEV creates .env itself)
ddev exec npm install                   # Install Node dependencies
ddev exec php artisan migrate           # Run migrations
ddev exec php artisan tenancy:backfill  # Setup multi-tenancy (creates default tenant)
ddev exec php artisan db:seed           # Seed demo data (tenants, roles)
ddev exec npm run build                 # Build frontend assets (public routes and /admin need the Vite manifest)

DDEV cannot change the database engine of an existing project. On a database type mismatch, recreate the project once:

ddev delete --omit-snapshot && ddev start

Production deployment

The production path is the CIVITAS/CORE add-on: the cividash-addon repository holds a Helm chart that the CORE platform deployment (Ansible) installs, together with the Keycloak client and the APISIX route. It runs the release images ghcr.io/jandaroscher/cividash-app and ghcr.io/jandaroscher/cividash-web, pinned to a release tag X.Y.Z (pin the image digest if you need byte-identical images). How CiviDash fits into CORE is described in docs/architecture/civitas-core/architecture.md.

Other setups:

Hosted deployments are maintained outside this repository.

Services and ports

Service What runs Port Configured by
cividash-web nginx (rootless) from the cividash-web image, serves public/ and passes PHP to cividash-fpm 8080 in the container; the add-on's Kubernetes Service maps 80 to 8080 docker/production/nginx/nginx.conf
cividash-fpm PHP-FPM from the cividash-app image (Laravel, Filament, API) 9000 (FastCGI) docker/production/php/www.conf
cividash-queue (add-on) php artisan queue:work, same app image none QUEUE_CONNECTION (default database)
cividash-scheduler (add-on) php artisan schedule:run every 60 seconds, same app image none routes/console.php
cividash-migrate one-shot php artisan migrate --force before each rollout none DB_*
cividash-seed (add-on) one-shot seed job after each install and upgrade: creates the default tenant if missing, sets its domain and, if enabled, updates seeded pages none add-on docs/seed.md
PostgreSQL 16 application database (all tenants in one database; sessions, cache and queue tables) 5432 DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
S3-compatible storage public media (uploads) when PUBLIC_DISK_DRIVER=s3; otherwise a shared volume on storage/app/public as in AWS_ENDPOINT PUBLIC_DISK_DRIVER, AWS_*, PUBLIC_S3_BUCKET, FILESYSTEM_PUBLIC_URL
Keycloak (optional) OpenID Connect login for the admin panel as in KEYCLOAK_BASE_URL KEYCLOAK_*
CIVITAS/CORE broker (optional) NGSI-LD source for the scheduled data sync as in CIVITAS_API_URL CIVITAS_*

The Docker Compose smoke stack (docker/production/docker-compose.smoke.yml) publishes cividash-web on host port 8088. The health endpoint is /up.

Configuration

All deployment settings come from environment variables, read through config/*.php; per-tenant panel settings such as branding are stored in the database. The entrypoint of the app image runs config:cache at container start, so a changed variable needs a restart. .env.production.example lists the production variables with secret/non-secret markers, and installation-standalone.md explains more of them. Defaults below are the code defaults from config/.

Group Key Default Purpose
App APP_KEY none Encryption key, secret. Keep it stable; changing it invalidates sessions and encrypted data
App APP_ENV / APP_DEBUG production / false integration:sync-civitas and dashboard:reset only run on schedule with APP_ENV=production
App APP_URL http://localhost Public base URL; CORS origins are derived from its host
App APP_LOCALE / APP_TIMEZONE en / Europe/Berlin Default locale (de or en) and timezone
Database DB_CONNECTION sqlite Set to pgsql; PostgreSQL 16 is the only target tested in CI
Database DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORD 127.0.0.1 / 5432 / laravel / root / empty PostgreSQL connection; the password is secret
State SESSION_DRIVER / CACHE_STORE / QUEUE_CONNECTION database Shared state in the database, no Redis needed
State SESSION_SECURE_COOKIE unset Set to true behind TLS
Media PUBLIC_DISK_DRIVER local s3 stores public media in object storage
Media FILESYSTEM_PUBLIC_URL /storage Public base URL of media, see Media on S3
Media AWS_ENDPOINT / PUBLIC_S3_BUCKET / AWS_USE_PATH_STYLE_ENDPOINT empty / AWS_BUCKET / false S3-compatible endpoint, bucket, path-style URLs (true for MinIO/RustFS). The bucket falls back to AWS_BUCKET only if PUBLIC_S3_BUCKET is unset, not if it is empty as in .env.production.example
Media AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY empty S3 credentials, secret
Proxy TRUSTED_PROXIES * Proxies whose X-Forwarded-* headers are trusted
Logging LOG_CHANNEL / LOG_LEVEL stack / debug Use stderr and warning or info in containers
CORE sync CIVITAS_ENABLED false Enables the scheduled integration:sync-civitas pull
CORE sync CIVITAS_API_URL / CIVITAS_DRIVER http://localhost:8080/context/ngsi-ld/v1 / ngsi-ld Broker URL and driver (ngsi-ld or sensorthings)
CORE sync CIVITAS_OAUTH_TOKEN_URL / CIVITAS_OAUTH_CLIENT_ID / CIVITAS_OAUTH_CLIENT_SECRET empty OAuth2 client credentials for the broker; the secret is secret
CORE sync CIVITAS_SYNC_SCHEDULE daily daily (04:00) or hourly
SSO KEYCLOAK_SSO_ENABLED / KEYCLOAK_SSO_PASSWORD_LOGIN false / true Keycloak login for the admin panel; false disables password login while SSO is on
SSO KEYCLOAK_BASE_URL / KEYCLOAK_REALM / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET empty / civitas / empty / empty OIDC client; the secret is secret
Demo DASHBOARD_DEMO_RESET false true deletes all content of the default tenant and reseeds Demo City nightly. Never enable on real data

Media on S3

With PUBLIC_DISK_DRIVER=s3 the app stores uploads at the root of PUBLIC_S3_BUCKET and answers /storage/<path> itself by reading the object with its own credentials. The bucket can stay private, but every object in it can be fetched by its key, so use a bucket for public media only (not the AWS_BUCKET of FILESYSTEM_DISK=s3). FILESYSTEM_PUBLIC_URL decides where browsers load media from:

  • empty or /storage: from the app, on whichever domain the dashboard is opened. Use this when tenants have their own domains. Share images (og:image) are then relative URLs.
  • https://<app host>/storage: from the app on one fixed host, with absolute share images.
  • the bucket URL, e.g. https://s3.example.org/cividash: straight from the bucket. This needs anonymous read (s3:GetObject) on the bucket and the bucket origin in the CSP.

Up to 1.1.2 the s3 driver prefixed every object key with the container's storage path (/var/www/html/storage/app/public/). After upgrading, move existing objects to the bucket root (strip that prefix) or upload them again, and re-import theme bundles, which store absolute media URLs.

Documentation

Contributing

See CONTRIBUTING.md.

Where maintenance happens

GitHub is the working and release repository. Development, issues and pull requests, dependency updates (Dependabot), releases (tags, GitHub Releases and CHANGELOG.md, created by release-please) and the production images ghcr.io/jandaroscher/cividash-app and ghcr.io/jandaroscher/cividash-web all come from https://github.com/jandaroscher/cividash. Watch that repository for new releases and security fixes. The openCode repository is a mirror for discoverability; changes made there are not merged back.

Privacy

CiviDash ships with no tracking out of the box: no web analytics, no tag manager, no social media plugins, no video embeds and no fonts or avatars loaded from third-party servers (the bundled fonts are served locally; tests/Feature/Privacy/NoThirdPartyHostsTest.php guards this). The public frontend and tile embeds set no cookies and start no server-side session, so nothing about anonymous visitors (IP address, user agent) is stored in the database (tests/Feature/Privacy/AnonymousVisitorSessionTest.php). Only the admin panel uses a session cookie. The frontend uses localStorage for functional state (language, help hints), so no consent banner is required. The cividash-web access log records time, method, path without query string, status, size and duration, but no IP address, user agent or referer, and cividash-fpm writes no access log. Error logs of nginx still contain the client address of the failed request. Adding tracking is an operator decision and requires a code change; it cannot be switched on by configuration.

Contact and security

License

Licensed under the EUPL-1.2 or (at your option) any later version (SPDX: EUPL-1.2+). See LICENSE for the full text and NOTICE for bundled third-party components. From v1.1.0 on, every release carries SPDX SBOMs: one for the locked production dependencies from Composer and npm including all transitive packages (development tooling is left out), and one for each container image.

About

CiviDash – open-source sustainability dashboard for municipalities (Laravel, Filament, Vue). Mirror of openCode.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages