Skip to content

Add "make migrate" step to backend setup guide in contributing docs #1958

Description

@Konstantin-Zhukov

Description

The backend setup guide at contributing/getting-started is missing a critical step: running database migrations before starting the application. Without this step, new contributors will encounter a crash on first run with errors like relation "config" does not exist and relation "policies" does not exist, which are confusing and not self-explanatory.

Problem / Motivation

The current Step 4 instructs contributors to run make immediately after docker compose up -d. However, on a fresh database the schema does not exist yet. The app starts, the casbin access control adapter auto-creates the casbin_rule table, and then crashes trying to access tables that were never migrated. If the contributor then runs make migrate to fix it, the migration fails with multiple primary keys for table "casbin_rule" because casbin already created that table — making the situation even harder to debug.

The fix requires a strict ordering: migrate first, run second.

Proposed Solution

Insert a new step between the current Step 3 (start Docker services) and Step 4 (start the application) in the Setting Up DevGuard Backend Locally section of src/pages/contributing/getting-started.mdx:

Step 3: Start the necessary services
  docker compose up -d

Step 4: Run database migrations   ← NEW
  make migrate

Step 5: Start the application
  make run

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions