Creating an Admin User

stac-gis Core uses role-based access control. On a fresh database there is no admin account - every registered user starts with the user role. To use the admin panel (collections, vectors, users, knowledge base, and other restricted endpoints) you need at least one account with the admin role.

The quickest way to create one is to step into the PostgreSQL db service and flip an existing user's role column from user to admin. That is the main method on this page. A seed-script alternative is provided at the end for development.

ℹ️ All relative paths below assume you are in the repository root (core/).

The database service is named db in both the development compose (backend/stacgis/docker-compose.yml) and the production compose (core/docker-compose.yml). Default credentials are postgres / postgres and the database name is stacgis.

Roles & account status

Field	Allowed values	Meaning
role	admin · moderator · surveyor · user	admin has full privileges; user is the default
status	active · inactive · suspended · pending_verification	Account state; active is required to log in
is_email_verified	true / false	Gates login until the account is verified

To be a usable admin, set role = 'admin', and make sure status = 'active' and is_email_verified = TRUE so the account can sign in immediately.

---

Option 1 - Promote an existing user (recommended)

⚠️ Do this only for an account you control (e.g. your own). This grants full administrative privileges over the platform.

1. Make sure the account exists

The user must already be in the users table (for example, you signed up through the app or the API). If no user exists yet, use Option 2 to create one first.

2. Enter the db service

cd backend/stacgis
docker compose exec db psql -U postgres -d stacgis

You are now inside a psql session attached to the running stacgis database. (If you are running the root production stack from core/, run the same command from that directory: docker compose exec db psql -U postgres -d stacgis.)

3. Find the account

SELECT id, email, username, role, status, is_email_verified
FROM users
WHERE email = 'you@example.com';

Note the email (or the id) - you will use it in the next step.

4. Promote the account to admin

UPDATE users
SET role = 'admin',
    status = 'active',
    is_email_verified = TRUE
WHERE email = 'you@example.com';

Prefer updating by user ID?

UPDATE users
SET role = 'admin',
    status = 'active',
    is_email_verified = TRUE
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

5. Verify and exit

SELECT email, username, role, status, is_email_verified
FROM users
WHERE email = 'you@example.com';
-- expected: role = admin | status = active | is_email_verified = true

\q

Log in with that account in the frontend - the admin panel and admin-only endpoints are now available.

---

Option 2 - Seed a default admin (development)

The backend ships a seeding script that creates a ready-made admin account (admin@example.com / AdminPassword123!) plus a few demo users. Run it inside the API container:

cd backend/stacgis
docker compose run --rm api python scripts/seed_data.py

🛑 Change this password before leaving the development environment. It is a hard-coded default for convenience and must never be used in production.

---

Production notes

• In the production stack the database credentials come from environment variables (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB). Replace the defaults above with yours:

  cd core
  docker compose exec db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"

• If you are not on the Docker network, you can also reach the database with a local Postgres client using the same credentials as DATABASE_URL in backend/stacgis/.env (e.g. psql -h <host> -U postgres -d stacgis).

• Promoting users is an administrative, out-of-band action. There is no self-service "make me an admin" endpoint by design.

Verifying via the API

Once an admin is signed in, confirm the role is applied:

# Base URL is /api/v1 (see the frontend VITE_API_BASE_URL / backend API_V1_PREFIX)
curl -s -X GET "http://localhost:8000/api/v1/users/me" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

The response should include "role": "admin". You can also check any admin-gated endpoint from the interactive docs at http://localhost:8000/docs.

Revoking admin

To remove admin privileges (returns the account to a regular user):

UPDATE users
SET role = 'user'
WHERE email = 'you@example.com';

Troubleshooting

Symptom	Fix
psql: command not found inside the container	Use docker compose exec db psql -U postgres -d stacgis (from the compose-file dir)
ERROR: relation "users" does not exist	Migrations have not run - run docker compose run --rm api alembic upgrade head first
0 rows updated	No matching email/ID - re-run the SELECT in step 3 to confirm the account exists
Can log in but admin panel is hidden / 403	Confirm status = 'active' and is_email_verified = TRUE, then log in again
Multiple admin accounts	Fine - any user with role = 'admin' is a valid administrator