Deployment checks#
- Validate the server YAML, then validate with resolved environment values.
- Confirm the migration container exits successfully before the server starts.
- Check container logs and the API root through the public HTTPS origin.
- Sign in through a real client using a provisioned account or SSO.
- Record a short sample and verify stored audio and finished transcription.
- Confirm that your backup process covers the database and object storage.
A successful configuration validation checks structure and values, not database connectivity, storage access or inference credentials. A responding API root confirms the HTTP process; a successful transcription checks a much larger part of the deployment.
Server checks#
For the container deployment in server setup:
docker compose --env-file secrets.env ps --all
docker compose --env-file secrets.env logs --tail=100 db-migrator server
curl --fail https://api.dicto.example.com/
curl --fail https://api.dicto.example.com/info/v1/server_info
/health and /metrics are installed only with monitoring.enabled: true. A separate monitoring port may be configured. Keep metrics exposure aligned with your deployment's access rules.
Common symptoms#
| Symptom | Check |
|---|---|
| Server rejects YAML |
Unknown or duplicate keys,
config_version
, required sections, model IDs/defaults, matching release schema
|
| Missing environment variable | YAML references, container env_file, and whether the name has a non-blank value |
| Server ignores old env settings | Server 2.0 reads YAML; environment values only apply through explicit YAML references |
| Database connection fails | DNS/network reachability, credentials, TLS requirements, database existence and migrations |
| Stored audio fails | Bucket exists, access policy, endpoint/region, or persistent filesystem mount in the server |
| HTTP S3 endpoint rejected | storage.allow_http: true must be explicit when using HTTP |
| Transcription never finishes | Server logs, full provider API root, selected model, credentials and worker capacity |
| API works but browser fails |
Browser-accessible API URL, HTTPS, trusted origins and proxy behavior; app custom-server selection or management runtime
.env
|
| Desktop config appears ignored | Correct executable directory, valid YAML/schema version, and app restart |
| SSO callback fails | Auth base URL, provider settings, allowed origins and registered callback URI |
| Admin seeding creates no user | Seeding enabled with email/password; an existing user causes the seeder to skip |
/health returns 404 |
Monitoring may be disabled or listening on a separate port |
Share useful diagnostics#
Record the server and client versions, time of failure, public endpoint, affected operation and relevant container logs. Redact credentials and sensitive recording/transcription content before sharing diagnostics.
For a deployment upgrade, keep configuration changes with the release identifier so a reviewer can see exactly what changed. A rollback plan must account for the database schema and stored objects as well as the container image.
Client configuration errors#
The desktop app rejects unknown fields, invalid types, unsupported enum values, invalid API URLs and trace sample rates outside 0–1. Diagnostics identify the affected field and YAML position without printing credential values. Check the app schema for the accepted settings.
If an error reports a legacy config.json, migrate it to config.yaml, add config_version: 1, and remove the JSON file. A missing managed configuration uses release defaults; an invalid managed configuration does not.