Commands Reference

Quick reference for common commands used in Noumaris development and deployment.

Backend (Python/Poetry)

Poetry (Dependency Management)

Command	Description
poetry install	Install all dependencies from lock file
poetry shell	Activate virtual environment
poetry add package-name	Add new dependency
poetry add -D package-name	Add dev dependency
poetry update	Update all dependencies
poetry show	List installed packages
poetry env info	Show virtualenv information
poetry run python script.py	Run command in virtual environment

Alembic (Database Migrations)

Command	Description
alembic upgrade head	Apply all pending migrations
alembic downgrade -1	Rollback one migration
alembic downgrade <revision>	Rollback to specific version
alembic revision --autogenerate -m "msg"	Auto-generate migration from model changes
alembic revision -m "msg"	Create blank migration
alembic current	Show current database version
alembic history	View migration history
alembic show <revision>	Show details of specific migration
alembic stamp head	Mark database as current version (no changes)

Uvicorn (Backend Server)

Command	Description
python -m uvicorn src.noumaris_backend.api.main:app --reload	Run dev server with auto-reload
python -m uvicorn src.noumaris_backend.api.main:app --reload --port 8001	Run on custom port
PORT=8001 python -m uvicorn src.noumaris_backend.api.main:app --reload	Run on custom port (env var)
uvicorn src.noumaris_backend.api.main:app --workers 4	Run with multiple workers

Database Seeding

Command	Description
python seed_db.py	Seed templates, tags, demo users, institution
python scripts/seed_features.py	Seed feature permissions

Testing

Command	Description
pytest	Run all tests
pytest tests/test_api.py	Run specific test file
pytest tests/test_api.py::test_function	Run specific test
pytest -v	Verbose output
pytest -s	Show print statements
pytest --cov	Run with coverage report

Frontend (Node/npm)

npm (Package Management)

Command	Description
npm install	Install all dependencies
npm install package-name	Add new dependency
npm install -D package-name	Add dev dependency
npm update	Update all dependencies
npm list	List installed packages
npm audit	Check for security vulnerabilities
npm audit fix	Auto-fix vulnerabilities
npm run <script>	Run script from package.json

Development Servers

Command	Description
npm run dev	Run development server (uses .env.development)
npm run localhost	Run local dev server (uses .env.localhost)
npm run preview	Preview production build
npm run dev -- --port 5174	Run on custom port

Build Commands

Command	Description
npm run build	Build for production (default)
npm run build:dev	Build for development environment
npm run build:staging	Build for staging environment
npm run build:prod	Build for production environment
npm run build-keycloak-theme	Build Keycloak custom theme JAR

Linting & Quality

Command	Description
npm run lint	Run ESLint
npm run lint:fix	Auto-fix linting issues

Docker & Docker Compose

Docker Compose (Multi-Service)

Command	Description
docker-compose up -d	Start all services in background
docker-compose down	Stop and remove all containers
docker-compose ps	List running containers
docker-compose logs -f	Tail logs from all services
docker-compose logs -f <service>	Tail logs from specific service
docker-compose restart <service>	Restart specific service
docker-compose stop <service>	Stop specific service
docker-compose start <service>	Start specific service
docker-compose exec <service> <command>	Run command in running container
docker-compose build	Rebuild all images
docker-compose pull	Pull latest images

Service names: postgres, keycloak

Docker (Individual Containers)

Command	Description
docker ps	List running containers
docker ps -a	List all containers (including stopped)
docker logs -f <container>	Tail logs from container
docker exec -it <container> <command>	Run command in container
docker stop <container>	Stop container
docker rm <container>	Remove container
docker images	List images
docker rmi <image>	Remove image
docker system prune	Remove unused containers, images, networks

PostgreSQL (via Docker)

Command	Description
docker exec -it noumaris-postgres psql -U medical_user -d medical_db	Connect to PostgreSQL
docker exec -it noumaris-postgres pg_dump -U medical_user medical_db > backup.sql	Backup database
docker exec -i noumaris-postgres psql -U medical_user -d medical_db < backup.sql	Restore database

PostgreSQL Commands (inside psql):

• \dt - List tables
• \d table_name - Describe table schema
• \l - List databases
• \du - List users
• \q - Quit

Git

Basic Workflow

Command	Description
git status	Show working tree status
git add .	Stage all changes
git add <file>	Stage specific file
git commit -m "message"	Commit staged changes
git push	Push commits to remote
git pull	Pull latest changes
git fetch	Fetch remote changes (no merge)

Branching

Command	Description
git branch	List local branches
git branch <name>	Create new branch
git checkout <branch>	Switch to branch
git checkout -b <branch>	Create and switch to branch
git merge <branch>	Merge branch into current
git branch -d <branch>	Delete local branch
git push origin --delete <branch>	Delete remote branch

History & Diff

Command	Description
git log	View commit history
git log --oneline -10	View last 10 commits (compact)
git log --graph	View history as graph
git diff	Show unstaged changes
git diff --staged	Show staged changes
git diff <branch>	Compare with another branch
git show <commit>	Show commit details

Undoing Changes

Command	Description
git reset HEAD <file>	Unstage file
git reset --soft HEAD~1	Undo last commit (keep changes staged)
git reset --mixed HEAD~1	Undo last commit (keep changes unstaged)
git reset --hard HEAD~1	Undo last commit (discard changes) ⚠️
git checkout -- <file>	Discard changes in file
git revert <commit>	Create new commit that undoes changes

Stashing

Command	Description
git stash	Save uncommitted changes
git stash list	List stashed changes
git stash pop	Apply and remove latest stash
git stash apply	Apply latest stash (keep in list)
git stash drop	Delete latest stash
git stash clear	Delete all stashes

Rebasing

Command	Description
git rebase <branch>	Rebase current branch onto another
git rebase -i HEAD~3	Interactive rebase of last 3 commits
git rebase --continue	Continue rebase after resolving conflicts
git rebase --abort	Cancel rebase

Terraform

Initialization

Command	Description
terraform init	Initialize Terraform working directory
terraform init -upgrade	Upgrade provider versions

Planning & Applying

Command	Description
terraform plan	Preview changes
terraform apply	Apply changes
terraform apply -auto-approve	Apply without confirmation
terraform apply -var 'key=value'	Apply with variable
terraform destroy	Destroy all resources

State Management

Command	Description
terraform show	Show current state
terraform state list	List resources in state
terraform state show <resource>	Show resource details
terraform refresh	Update state from real infrastructure
terraform output	Show output values

Workspaces

Command	Description
terraform workspace list	List workspaces
terraform workspace new <name>	Create workspace
terraform workspace select <name>	Switch workspace
terraform workspace show	Show current workspace

Noumaris workspaces: dev, staging, production

Validation

Command	Description
terraform validate	Validate configuration syntax
terraform fmt	Format configuration files
terraform fmt -check	Check if formatting is needed

Google Cloud (gcloud)

Authentication & Config

Command	Description
gcloud auth login	Authenticate with Google account
gcloud config set project <project-id>	Set active project
gcloud config list	Show current configuration

Cloud Run

Command	Description
gcloud run services list	List Cloud Run services
gcloud run services describe <service> --region <region>	Show service details
gcloud run services update <service> --region <region>	Update service configuration
gcloud run services delete <service> --region <region>	Delete service
gcloud run revisions list --service <service> --region <region>	List revisions
gcloud run deploy <service> --image <image> --region <region>	Deploy service

Cloud Run Logs

Command	Description
gcloud run services logs tail <service> --region <region>	Tail logs
gcloud run services logs read <service> --region <region> --limit 100	Read recent logs

Cloud SQL

Command	Description
gcloud sql instances list	List Cloud SQL instances
gcloud sql instances describe <instance>	Show instance details
gcloud sql databases list --instance <instance>	List databases
gcloud sql backups list --instance <instance>	List backups
gcloud sql backups create --instance <instance>	Create backup

Secret Manager

Command	Description
gcloud secrets list	List secrets
gcloud secrets create <name> --data-file=<file>	Create secret from file
gcloud secrets versions access latest --secret <name>	View secret value
gcloud secrets delete <name>	Delete secret

Cloud Build

Command	Description
gcloud builds list	List builds
gcloud builds submit --config cloudbuild.yaml	Trigger manual build
gcloud builds log <build-id>	View build logs

Local Keycloak Setup

Terraform Configuration

Command	Description
bash scripts/setup-local-keycloak.sh	Run automated Keycloak setup
cd terraform/keycloak && terraform apply	Apply Keycloak configuration manually
cd terraform/keycloak && terraform apply -var 'login_theme=noumaris'	Apply with custom theme

Documentation

VitePress

Command	Description
cd docs && npm run docs:dev	Run documentation dev server
cd docs && npm run docs:build	Build documentation
cd docs && npm run docs:preview	Preview built documentation

Documentation URL: http://localhost:5174

Shortcuts & Tips

Quick Start (Local Development)

# Terminal 1: Docker services
docker-compose up -d

# Terminal 2: Backend
cd backend && poetry shell
python -m uvicorn src.noumaris_backend.api.main:app --reload

# Terminal 3: Frontend
cd frontend && npm run localhost

# Terminal 4: Documentation (optional)
cd docs && npm run docs:dev

Database Reset (Local)

# Stop containers
docker-compose down

# Remove volumes (⚠️ deletes data)
docker volume rm noumaris_postgres_data

# Restart
docker-compose up -d

# Wait 30 seconds, then run migrations
cd backend
alembic upgrade head
python seed_db.py

Clean Install

# Backend
cd backend
rm -rf .venv poetry.lock
poetry install

# Frontend
cd frontend
rm -rf node_modules package-lock.json
npm install

Next Steps

• Development Guide - Development workflows
• Troubleshooting Guide - Common issues
• Glossary - Term definitions