allucanget/calminer-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: update database initialization and seeding instructions in installation guide

Browse Source
This commit is contained in:
zwitschi
2025-11-12 18:17:20 +01:00
parent c9ac7195c7
commit 747f430562
1 changed files with 16 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
admin/installation.md
View File

@@ -65,37 +65,36 @@ Before you begin, ensure that you have the following prerequisites installed on
Once the containers are up and running, you can access the Calminer application by navigating to `http://localhost:8003` in your web browser.
If you are running the application on a remote server, replace `localhost` with the server's IP address or domain name.
5. **Database Initialization**
5. **Database Initialization & Seed Data**
The application container executes `/app/scripts/docker-entrypoint.sh` before launching the API. This entrypoint runs `python -m scripts.run_migrations`, which applies all Alembic migrations and keeps the schema current on every startup. No additional action is required when using Docker Compose, but you can review the logs to confirm the migrations completed successfully.
On container startup the FastAPI application executes `scripts.init_db` during the first `startup` event. This idempotent initializer performs the following steps:
For local development without Docker, run the same command after setting your environment variables:
- ensures PostgreSQL enum types exist (no duplicates are created),
- creates the core tables required for authentication, pricing, projects, scenarios, financial inputs, and simulation parameters,
- seeds default roles, admin user, pricing settings, and demo projects/scenarios/financial inputs using `INSERT ... ON CONFLICT DO NOTHING` semantics.
No additional action is required when using Docker Compose—the `uvicorn` process runs the initializer automatically before the bootstrap routines.
For local development without Docker, run the initializer manually after exporting your environment variables:
```bash
# activate your virtualenv first
python -m scripts.run_migrations
python -m scripts.init_db
```
The script is idempotent; it will only apply pending migrations.
Running the script multiple times is safe; it will reconcile records without duplicating data.
6. **Seed Default Accounts and Roles**
6. **Resetting the Schema (optional)**
After the schema is in place, run the initial data seeding utility so the default roles and administrator account exist:
To rebuild the schema from a clean slate in development, use the reset utility which drops the managed tables and enum types before rerunning `init_db`:
```bash
# activate your virtualenv first
python -m scripts.00_initial_data
CALMINER_ENV=development python -m scripts.reset_db
python -m scripts.init_db
```
The script reads the standard database environment variables (see below) and supports the following overrides:
- `CALMINER_SEED_ADMIN_EMAIL` (default `admin@calminer.local` for dev, `admin@calminer.com` for prod)
- `CALMINER_SEED_ADMIN_USERNAME` (default `admin`)
- `CALMINER_SEED_ADMIN_PASSWORD` (default `ChangeMe123!` — change in production)
- `CALMINER_SEED_ADMIN_ROLES` (comma list, always includes `admin`)
- `CALMINER_SEED_FORCE` (`true` to rotate the admin password on every run)
You can rerun the script safely; it updates existing roles and user details without creating duplicates.
The reset utility refuses to run when `CALMINER_ENV` indicates a production or staging environment, providing an extra safeguard against accidental destructive operations.
### Export Dependencies