Initial Setup¶

Step-by-step guide for the first-time setup of a calServer v2 instance with a complete database.

Prerequisites¶

calServer v1 is already running (docker-compose.yml)
Docker >= 24.0, Docker Compose >= 2.20
Database: PostgreSQL 16 (default); alternatively MySQL or Microsoft SQL Server, see System Requirements
.env file is configured (see Installation)

Quick Start (single command)¶

For the most common scenario — V1-compatible installation on an empty database:

docker exec calserver-api-v2 php artisan db:install --v1 --clean --force

This command automatically performs all steps:

Drop existing tables (--clean)
Run all migrations
Create superadmin user + RBAC permissions
Seed system property defaults
Load V1 system data (field configurations, grid templates, languages)
Run V1 compatibility verification

Step-by-Step Installation¶

If you need more control over the process:

Step 1: Run Migrations¶

docker exec calserver-api-v2 php artisan migrate

Creates all database tables. The migrations are compatible with the existing V1 table structure.

Step 2: System Setup (RBAC + Superadmin)¶

docker exec calserver-api-v2 php artisan app:setup

Creates:

Superadmin user with hidden_super_admin role
RBAC groups (27 groups such as inventory_management, calibration_management, etc.)
RBAC operations (~110 permissions such as inventory_view, calibration_edit, etc.)
Links all operations to the superadmin role

Superadmin Credentials


Email	`superadmin@calhelp.de`
Password	(set during installation)

The password must be changed after the first login.

Step 3: Seed System Properties¶

This step is included in db:install. For manual installation:

docker exec calserver-api-v2 php artisan db:seed --class=InitialDataSeeder

Sets default values for user, calibration, and customer settings.

Step 4: Load V1 System Data (optional)¶

docker exec calserver-api-v2 php artisan db:seed --class=DemoSetupSeeder

Loads V1 system configuration from SQL files:

Languages
Field configurations
Grid setting templates
Grid sort defaults

V1 Compatibility

This step is required if the instance needs to work with an existing V1 installation. Without this data, field configurations and grid templates will be missing.

Step 5: Import Report Packages¶

A fresh installation prints nothing until report templates are imported. That is not a defect: the templates are maintained in calServer-reports and are deliberately not shipped inside the application image, so no second copy of them exists.

Download a package from calhelp.github.io/calServer-reports/downloads
Upload it under Administration → Report management

The three system reports already have a row after installation, naming the package that belongs in it:

Report	Reference package
Loan receipt	`LOCATION-JSON-SAMPLE`
Price list	`PRICE-LIST-JSON-SAMPLE`
Order document	`ORDER-JSON-SAMPLE`

Everything else — the calibration certificate first of all — is created as a report in the report management with its package uploaded to it. New templates should use the JSON data source rather than embedded SQL, see Authoring V2 reports with a JSON data source.

Templates carried over from V1

Classic V1 packages read the V1 tables. Against a pure V2 database they find nothing; calServer then aborts with a message instead of delivering an empty PDF. The fix is the JSON variant of the same template (e.g. DAKKS-JSON-SAMPLE instead of DAKKS-SAMPLE).

Seeding Demo Data¶

For testing and demonstration purposes, demo data can be seeded:

docker exec calserver-api-v2 php artisan demo:data seed --force

This creates:

3 test users with different permission levels
Test customers with instruments and calibrations
Representative field configurations
Locations, repairs, standards, contacts, categories, types, and additional test data

Test Users¶

Email	Password	Role
`admin@test.calserver.local`	`test-admin-password`	Admin (full access)
`viewer@test.calserver.local`	`test-viewer-password`	Read-only
`noapi@test.calserver.local`	`test-noapi-password`	No API access

Removing Demo Data¶

docker exec calserver-api-v2 php artisan demo:data remove --force

Cleanly removes all test data without affecting the system configuration.

Verification¶

Automatic Verification (recommended)¶

docker exec calserver-api-v2 php artisan db:install --v1

Automatically checks:

All V1-critical tables exist
RBAC operations and roles are present
Property defaults are set
translation_version is present (prevents V1 /update page)
Superadmin user exists
Total table count

Manual Verification¶

# Test login functionality
docker exec calserver-api-v2 php artisan auth:diagnose superadmin@calhelp.de --password='<YOUR-PASSWORD>'

Common Scenarios¶

Fresh Development Environment¶

# Set up database completely with V1 compatibility + demo data
docker exec calserver-api-v2 php artisan db:install --v1 --clean --force
docker exec calserver-api-v2 php artisan demo:data seed --force

Reset Database¶

# Drop everything and reinstall
docker exec calserver-api-v2 php artisan db:install --v1 --clean --force

Update Migrations Only (keep existing data)¶

docker exec calserver-api-v2 php artisan migrate

Run Tests Locally¶

cd laravel
composer fresh    # Fresh test DB with TestDatabaseSeeder
composer test     # All tests in parallel

Troubleshooting¶

# Run diagnostic tool
docker exec calserver-api-v2 php artisan auth:diagnose user@example.com --password='Password'

The tool checks database connection, user existence, password hash type, and verification.

V1 Shows `/update` Page¶

The translation_version property is missing. Run again:

docker exec calserver-api-v2 php artisan db:install --v1 --force

RBAC Errors (403 on API Calls)¶

Reset permissions:

docker exec calserver-api-v2 php artisan app:setup

Complete Database Reset¶

docker exec calserver-api-v2 php artisan db:clear --force
docker exec calserver-api-v2 php artisan db:install --v1 --force