02 — Backend (Django)

Overview of backend modules — what each part does, where to find things, and what to watch out for.

Django Applications

Models — Where things live

All models are in forge/main/models/. Each file covers one domain area:

Watch out

• UnifiedJob pattern: Every executable (JobTemplate, Project, InventorySource) follows the same pattern — a template creates an instance. If you understand UnifiedJobTemplate → UnifiedJob, you understand all job types.

• Credential encryption: Fields marked as secret in CredentialType.inputs are encrypted before saving. Never read credentials directly from the database — use the API.

• Computed fields on Inventory: total_hosts, hosts_with_active_failures, etc. are updated via signals. If you add a host directly to the database (not through the API), these fields won't update until update_computed_fields() is called.

• Organization is required: Almost every resource requires an organization FK. Without an organization, RBAC won't work because roles are inherited from the organization.

REST API — Structure

The API is in forge/api/ and follows DRF (Django REST Framework) conventions.

File locations

API conventions

• List: GET /api/v2/{resource}/ → paginated JSON with count, next, previous, results
• Detail: GET /api/v2/{resource}/{id}/ → single object
• Create: POST /api/v2/{resource}/ → body with data
• Update: PATCH /api/v2/{resource}/{id}/ → partial update
• Delete: DELETE /api/v2/{resource}/{id}/ → 204 No Content
• Actions: POST /api/v2/{resource}/{id}/{action}/ → launch, cancel, update...
• Nested: GET /api/v2/{parent}/{id}/{child}/ → related resources

Watch out

• related field: Every API response has a related dict with URLs to related resources. Use this instead of manually constructing URLs.

• summary_fields: Inline data about related objects (organization name, project name...). This eliminates the need for additional API calls.

• OPTIONS request: Every endpoint returns metadata about available fields and actions via OPTIONS. Useful for dynamically generating forms.

• RBAC filtering: List endpoints automatically filter results based on user permissions. An admin sees everything; a regular user sees only what they have access to.

Signals — Automatic side-effect actions

Signals are in forge/main/signals.py and automatically react to database changes:

Watch out: Signals execute synchronously — if a signal throws an exception, the entire transaction is rolled back. If you see unexpected IntegrityError, check if a signal is attempting something invalid.

Management Commands

Commands are in forge/main/management/commands/. They are run with forge-manage (or awx-manage — both work, backward compatibility).

Most important commands

Instance management: - forge-manage provision_instance --hostname=node1 — register a new cluster node - forge-manage deprovision_instance --hostname=node1 — remove a node - forge-manage list_instances — show all nodes with capacity

Users: - forge-manage createsuperuser — create admin user - forge-manage update_password --username=admin --password=new — reset password

Database: - forge-manage migrate — apply migrations - forge-manage check_db — verify database connectivity - forge-manage dbshell — open PostgreSQL shell

Cleanup (run periodically): - forge-manage cleanup_jobs --days=90 — delete old jobs and events - forge-manage cleanup_sessions — delete expired sessions - forge-manage cleanup_tokens — delete expired OAuth tokens

Diagnostics: - forge-manage check_instance_ready — is the node ready for work - forge-manage stats — system statistics

Watch out

• cleanup_jobs is critical for production. Without it, the job event table grows without limit. Recommendation: set up as a System Job that runs daily.

• provision_instance is automatically called in the init script during deployment. You only run it manually when adding new nodes to the cluster.

Configuration System — Two levels

Level 1: File-based (Django settings)

Loaded at startup, cannot be changed without restart.

Level 2: Database-backed (Forge conf system)

Stored in PostgreSQL, changed via API (/api/v2/settings/) without restart.

Registered in forge/conf/ and covering: job timeouts, LDAP configuration, logging, notifications, and much more.

Watch out: Database settings override file settings. If something isn't working as expected, check if it's been overridden in the database:

forge-manage print_setting SETTING_NAME

Migrations

Forge has 252 Django migrations in forge/main/migrations/.

Watch out

• All migrations reference forge.main.fields — not awx.main.fields. If you create a new migration, makemigrations will automatically use the correct prefix.

• Never edit existing migrations — only add new ones.

• If a migration fails, check forge-manage showmigrations | grep "\[ \]" to see which ones are unapplied.

• The init script automatically runs migrate during deployment.