services.yaml — referenceThe project-wide service registry. Declares profiles (which services activate together), command structure, port allocation patterns, credential patterns. Single source of truth for cross-service config.
This is the project-level counterpart to per-service manifest.yaml. One file at the repo root; every service in the project is referenced from here.
services.yaml
├── project: # Project metadata
├── command_structure: # Documentation of just command conventions
├── reference_services: # Default service per category
├── installation_defaults: # Patterns for new installs (ports, creds, naming)
├── command_types: # Logical command groups
├── profiles: # Named service subsets
└── services: # Cross-references to packages/*/manifest.yaml
Top of file:
version: 1.11.0 # current
projectProject-wide metadata.
project:
name: ASD Project Management Automation
description: "Manifest-driven multi-service self-hosted suite"
documentation: https://github.com/asd-engineering/asd-pma
support: https://github.com/asd-engineering/asd-pma/issues
command_structureDocuments the just command conventions. Not code — operator-facing docs.
command_structure:
global_commands:
description: "Cross-service commands (services-*, backup, restore, …)"
examples:
- services-status
- services-restart
- backup
per_service_commands:
description: "Service-specific commands ({svc}-*)"
pattern: "{service}-{verb}"
examples:
- redmine-status
- mattermost-create-user
reference_servicesFor each category, names the canonical service. Used when the framework needs a "default" service to demonstrate or test against.
reference_services:
project_management: redmine
analytics: superset
communication: mattermost
fallback: redmine # default-default
installation_defaultsPatterns the framework uses when registering new services. Keeps PMA's naming + port allocation consistent.
installation_defaults:
port_allocation:
range: 8080-8199
reserved: [8080, 8443] # blocked
credential_patterns:
db_password: "{service}-{random:32}"
admin_password: "{service}-admin-{random:24}"
database_patterns:
postgresql:
container: "${CONTAINER_PREFIX}${SERVICE}-postgres"
user: "${SERVICE}"
db: "${SERVICE}_production"
env_conventions:
pattern: "{SERVICE_UPPER}_VARIABLE"
examples:
- REDMINE_DB_PASSWORD
- MATTERMOST_PORT
container_naming:
prefix: "asd-${ASD_ENV}-"
pattern: "{prefix}{service}"
volume_naming:
pattern: "asd-{service}-data"
command_typesGroups of related commands. Useful for "list all backup commands" / "list all user commands" queries.
command_types:
lifecycle: [start, stop, restart, status, logs]
users: [list-users, create-user, delete-user, list-roles]
backup: [backup, restore, list-backups]
sso: [sso-add, sso-check, sso-fix]
profilesThe most-used section. Named subsets of services. just profile set <name> switches which services activate.
profiles:
minimal:
description: "Smallest install — Authentik + one app"
services: [authentik, redmine]
development:
description: "Day-to-day dev work"
services: [authentik, n8n, mattermost, redmine, wikijs]
enterprise:
description: "Full business suite"
services:
- authentik
- redmine
- mattermost
- n8n
- erpnext
- superset
- wikijs
- zammad
- grafana
- prometheus
- loki
- postal
support:
description: "Support-team-focused"
services: [authentik, n8n, mattermost, zammad, espocrm]
data:
description: "BI + observability"
services: [authentik, n8n, redash, superset, grafana, prometheus, loki]
full:
description: "Everything non-experimental"
services: [...] # union of all above
Profile operations:
just profile show # show active profile + service list
just profile list # list all profiles
just profile set enterprise # switch active profile
just profile enable <svc> # add service to active profile
just profile disable <svc> # remove
just profile compare # diff between profiles
just profile sync # update .env to match profile
servicesCross-references to per-service packages/<svc>/manifest.yaml. Doesn't duplicate — points.
services:
redmine:
manifest: packages/redmine/manifest.yaml
# optional override: short fields can be pinned here without
# editing the manifest itself (e.g. for environment-specific
# tweaks)
overrides:
port: 8083 # override the default port
mattermost:
manifest: packages/mattermost/manifest.yaml
# ...
The authoritative file lives at the asd-pma repo root: services.yaml. Schema validation via just contract-validate.
Edits typically happen for: adding a new profile, changing profile membership, adjusting port allocation defaults, registering a new service entry.
/pma/reference/manifest — per-service manifest schema (referenced from services.yaml.services.*.manifest)./pma/learn/03-multi-service-stack — using profiles to activate sets of services./pma/cookbook/install-a-new-service — adding a service registers it via services.yaml.