Installation

🧾 Overview

This guide outlines the required components and deployment structure for deploying an application with the following services:

API Service

Background Worker

These services utilize AWS Secrets Manager, Amazon RDS (PostgreSQL), ElastiCache (Redis), RabbitMQ, and Amazon S3 for storage and operational infrastructure.

🧱 Application Components

API Service

Container Port: 8000

Health Check Path:

{
  "protocol": "HTTP",
  "path": "/",
  "port": "traffic-port",
  "healthyThreshold": 5,
  "unhealthyThreshold": 2,
  "timeout": 5,
  "interval": 30,
  "successCodes": "200"
}

Min. System Requirement:

Memory: 2 GB RAM

CPU: 1 Core

Background Worker

Executes asynchronous tasks using Celery

Message broker: RabbitMQ

Health Check Command (CLI-based):

{
  "command": [
    "CMD-SHELL",
    "pipenv run celery -A project.celery_config:celery_app inspect ping || exit 1"
  ],
  "interval": 5,
  "timeout": 20,
  "retries": 3,
  "startPeriod": 10
}

Min. System Requirement:

Memory: 2 GB RAM

CPU: 1 Core

🔐 Required Environment Variables

These must be configured in ECS task definitions for both services:

aws_secret_name: Name of the secret in AWS Secrets Manager

aws_region: AWS region in which the services and secrets are deployed

These variables are used at runtime to fetch further configuration from AWS Secrets Manager.

🔑 Environment variables configuration

Sensitive configuration values should be stored securely in AWS Secrets Manager. The following key-value pairs must be defined:

Env keys are case sensitive

Envs can be passed by:

AWS Secret Manager aws_secret_name="" + aws_region=""

AWS SSM Parameter Store aws_ssm_path="" + aws_region="" + aws_ssm_recursive="true"

Env file env_file="file path"

System env variable

{
  "license_endpoint": "https://license.crego.io/verify", // Will be provided by Crego for kill switch
  "license_secret": "", // Will be provided by Crego for kill switch
  "secret_key": "your-secret-key", // Application secret key for cryptographic signing
  "db_host": "your-db-host.rds.amazonaws.com", // Database host (PostgreSQL)
  "db_name": "database_name", // Name of the application database
  "db_username": "db_user", // Username to access the database
  "db_password": "db_password", // Password for the database user
  "db_port": "5432", // PostgreSQL port (default 5432)

  "redis_host": "your-redis-host.cache.amazonaws.com", // Redis hostname for caching or Celery
  "redis_port": "6379", // Redis port (default is 6379)
  "rabbit_mq_uri": "amqps://user:pass@host:port/vhost", // RabbitMQ connection URI

  "service_host": "Hosted IP", // Backend service hostname IP
  "web_app_domain": "<https://web.example.com>", // Frontend web app domain
  "sentry_dns": "<https://<key>@o><org>.ingest.sentry.io/<project_id>", // Sentry DSN for logging (optional)
  "service_name": "omni", // Name of the backend service (default 'omni')
  "health_check_path": "/health/", // Health check endpoint (default '/health')
  "endpoint_prefix": "/", // APIs endpoint prefix
  "log_backends": "console,rsys", // Logging destinations (comma-separated)
  "rsys_host": "rsyslog.example.com", // Syslog server host (optional)
  "rsys_port": "514", // Syslog server port (default 514 for UDP)

  "oidc_client_id": "your-client-id", // OIDC client ID provided by your IdP
  "oidc_client_secret": "your-client-secret", // OIDC client secret
  "oidc_issuer": "<https://your-oidc-provider.com>", // Base domain for your OIDC provider
  "oidc_discovery_endpoint": "", // URL to fetch OpenID configuration
  "oidc_jwks_endpoint": "<https://your-oidc-provider.com/.well-known/jwks.json>", // URL to fetch JWKS for token verification
  "oidc_authorization_endpoint": "<https://your-oidc-provider.com/oauth2/authorize>", // URL for login redirect
  "oidc_token_endpoint": "<https://your-oidc-provider.com/oauth2/token>", // URL to exchange code for tokens
  "oidc_userinfo_endpoint": "<https://your-oidc-provider.com/oauth2/userinfo>", // URL to fetch user profile
  "oidc_logout_endpoint": "<https://your-oidc-provider.com/logout>", // OIDC logout URL

  "oidc_user_id_key": "sub", // Claim used as unique user ID
  "oidc_username_key": "preferred_username", // Claim representing the username
  "oidc_user_name_key": "name", // Claim for full name
  "oidc_user_email_key": "email", // Claim for email
  "oidc_user_phone_key": "phone_number", // Claim for phone number
  "oidc_user_role_key": "custom:role", // Custom role claim from the IdP
  "oidc_user_groups_key": "cognito:groups" // Claim listing user’s group memberships
  "oidc_staff_role": "staff" // Group name to make user as staff user
  "oidc_superuser_role": "superuser" // Group name to make user as superuser
}

☁️ Infrastructure Requirements

1. PostgreSQL

Purpose: Persistent database storage

Deployment: Self-managed or managed via Amazon RDS

Supported version 14.xx

2. Redis

Purpose: Celery result backend

Deployment: Self-managed or managed via Amazon ElastiCache

Supported version 6.2.6

3. Valkey

Alternative to Redis

Purpose: Celery result backend

Deployment: Self-managed or managed via Amazon ElastiCache

Supported engine >8

4. RabbitMQ

Purpose: Celery message broker

Deployment: Self-managed or managed via AWS MQ or other AMQP-compatible broker

5. Amazon S3

Purpose: File and document storage

Access is managed via web application, and is not part of the deployment environment variables

6. Authentication

Authentication is handled via any OIDC-compliant provider.

Optionally, Crego provides its own IAM service for centralized user and service authentication.

7. Logging

Logs are written to the container console by default.

These logs can be forwarded to any log management solution (e.g., CloudWatch, Datadog, ELK) based on deployment setup.

🧾 Overview#

🧱 Application Components#

API Service#

Background Worker#

🔐 Required Environment Variables#

🔑 Environment variables configuration#

☁️ Infrastructure Requirements#

1. PostgreSQL#

2. Redis#

3. Valkey#

4. RabbitMQ#

5. Amazon S3#

6. Authentication#

7. Logging#