Installation Process

To initially install your Generator instance, follow these steps. Rustici’s Delight team will work with you closely during this process, so we’ll be available to walk you through this and answer any questions you have.

Obtain Credentials:
- Rustici will securely provide credentials to access the repository containing the Generator release images.

Download the Image:

Use the provided credentials to download the Docker images onto the server(s) that will run your containers.

Example bash commands:

export AWS_ACCESS_KEY_ID=[your access key id]
export AWS_SECRET_ACCESS_KEY=[your access secret key]

# Log into release ECR repo
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 025066246552.dkr.ecr.us-east-1.amazonaws.com

# Download the release
# See our release notes for the latest version: https://support.scorm.com/hc/en-us/sections/31506360731931-Release-Notes
docker pull 025066246552.dkr.ecr.us-east-1.amazonaws.com/rustici-generator:[generator version, e.g. 1.6.0]

If you’re hosting the application in AWS ECS, you will need to download the image, retag it, and push it back up into your own ECR repo.

Create Database and RabbitMQ Broker:
- Install and start your PostgreSQL database and RabbitMQ broker. Refer to their respective documentation for details.
- Make sure your database and broker are somewhere accessible to the application.
  - PostgreSQL will require port 5432 by default (but can be configured with the DB__PORT setting)
  - The MQ broker will require port 5672 by default (but can be configured with the QUEUE__PORT setting)
- In our hosted environments, we rely on AWS RDS and AWS MQ to host these. We’ve also had success in developer environments using the vendor-provided Docker images.
- If you’re creating a fresh database server, make sure it has a fresh PostgreSQL database. Take note of its name, as you will need to set the DB__DATABASE setting to that database’s name.
- Generator uses the schemas public and content_store of the configured database. Create both of those schemas, and ensure the following extensions are installed in each:
  - Run CREATE EXTENSION pg_trgm WITH SCHEMA public
  - Run CREATE EXTENSION vector WITH SCHEMA content_store
Configure Database User Permissions:
Generator needs specific database permissions to run as intended. You can configure database users using one of the following methods:
Option 1: Separate Users (Recommended)
Create two distinct database users with different permission levels:
- Migration User: Requires full database ownership to perform schema migrations and upgrades
  - Full privileges on the database, including both public and content_store schemas
  - DDL operations: CREATE, ALTER, DROP on tables, sequences, functions, and other schema objects
  - Default privileges must be configured so that objects created by the migration user (tables, sequences) in both schemas are automatically accessible to the application user
  - Used only during initial setup and application upgrades
- Application User: Needs restricted permissions for normal application operations
  - USAGE ON SCHEMA permission for both public and content_store schemas (required in PostgreSQL to access schema contents)
  - Data manipulation only: SELECT, INSERT, UPDATE, DELETE on tables in both public and content_store schemas
  - Sequence permissions: USAGE and SELECT on sequences in both schemas
  - Permissions must be granted on both existing objects and future objects that will be created during migrations
  - No DDL capabilities (cannot create, alter, or drop database objects)
  - Used for all normal application operations
Option 2: Single User
Use one database user with combined permissions that can perform both migration and application tasks. This user must have all the permissions listed above for both roles.
Environment Variable Configuration:
Generator will use the database credentials defined in the DB__USER and DB__PASSWORD env variables.
- If using separate users, you will need to set these values to the migration user’s credentials during installation or upgrades and set them to the app user’s credentials for normal operations.
- If using a single user to run the app and handle the schema migrations, then you can use the same credentials for both.
Create S3 Bucket (Optional):
- If you want Generator to have its own S3 bucket, create one
  - Most of the default settings are appropriate for Generator:
    - Bucket type: General purpose
    - ACLs disabled
    - Block all public access
    - Default encryption: Your team’s choice
  - You may want to enable bucket versioning for the ability to roll back your data in the event of an incident.
- Alternatively, Generator can use an existing bucket
Set Up Environment Variables:
A comprehensive list of configurable variables, including descriptions and recommended values, is available on this page.
You can pass these environment variables into the app containers using the method that best suits your team’s workflow. Common approaches include:
- Recording them in a .env file.
- Passing them directly with the -e flag in the docker run command.
- Defining them in the task definition when using AWS ECS.
- Other container orchestration methods as applicable.
AWS Bedrock Model Subscriptions:
Generator uses different models for different operations to find the right balance between cost and performance. To ensure Generator has correct access, subscribe to the following models in your AWS account before deploying Generator:
- Cohere Embed (cohere.embed-multilingual-v3)
- Claude Haiku 3 (anthropic.claude-3-haiku-20240307-v1:0)
- Claude Haiku 3.5 (anthropic.claude-3-5-haiku-20241022-v1:0)
- Claude Haiku 4.5 (anthropic.claude-haiku-4-5-20251001-v1:0)
- Claude Sonnet 4 (anthropic.claude-sonnet-4-20250514-v1:0)
- Note that additional models may be required in future Generator releases, so you will need to monitor release notes and subscribe to new models as needed.
Create IAM Role:
The application will need access to a few AWS resources to run the application. To grant those permissions to the containers, you will need an IAM role.
Here are IAM permissions for that role based on what we use for our hosted Generator instances:
- AWS policies to attach to your IAM role:
  - Access to AWS Transcribe:
```
arn:aws:iam::aws:policy/AmazonTranscribeFullAccess
```
  - Permissions for running in ECS (includes permission to access ECR):
```
arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
```
  - Access to AWS Bedrock:
```
arn:aws:iam::aws:policy/AmazonBedrockFullAccess
```
- Policy statements based on what we use for our hosted Generator instances:
  - Permission to access secret values in SSM (if you’re using SSM to manage your secrets)
```
{
   "Action": [
      "ssm:GetParameters"
   ],
   "Effect": "Allow",
   "Resource": "arn:aws:ssm:REGION:ACCOUNT_ID:parameter/[SECRETS PREFIX]/*"
},
```
  - Permission to manage content in your S3 bucket:
```
{
   "Action": [
      "s3:Get*",
      "s3:List*",
      "s3:Put*",
      "s3:DeleteObject*"
   ],
   "Effect": "Allow",
   "Resource": [
      "arn:aws:s3:::[BUCKET NAME]",
      "arn:aws:s3:::[BUCKET NAME]/*"
   ]
},
```
Configure the Application with the Role:
There are a few ways that the role can be provided to the application:
- Using AWS ECS
  - If you are running your containers inside AWS managed services like ECS or EKS, you can assign an IAM role directly to the containers or pod, which removes the need to pass credentials manually.
- Use AWS EC2 instance profile
  - If you’re running the containers directly on an EC2 instance, you can configure the instance with an instance profile. That will bypass the need to provide credentials directly to the containers.
- Mount AWS credentials file into the container
  - If you are running the containers in a location that has AWS credentials stored in a file, you can mount those credentials inside the containers by including the argument -v ~/.aws:/root/.aws:ro in your docker run command (see Start the Containers below).
- Pass AWS credentials into the container as environment variables
  - If you’ve generated AWS credentials for a user that has your IAM role, you can provide those as environment variables in your docker run command with -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY.
Initialize Database Schema:
Before starting the application containers, you need to create the initial database schema. This step is required because the application user (if using separate users) doesn’t have the DDL permissions needed to create the initial schema.
- If using separate database users: Run the schema migration tool with the migration user credentials. See the Schema Migrations documentation for details.
- If using a single database user: You can skip this step as the application will create the schema automatically on first startup.
Start the Containers:
- Start at least one container each for the API and the worker.
  - The API container will need to expose port 80 to accept incoming requests.
  - The worker container requires the IS_WORKER environment variable to be set to true.
- Example command if running containers manually:
```
docker run --name rustici-generator-backend --env-file .env -p 80:80 -d 025066246552.dkr.ecr.us-east-1.amazonaws.com/rustici-generator:[generator version]
docker run --name rustici-generator-worker --env-file .env -e IS_WORKER=true -d 025066246552.dkr.ecr.us-east-1.amazonaws.com/rustici-generator:[generator version]
```
- Alternatively, you can run the containers in AWS ECS.
Verify API Functionality:
- Connect to the API over its IP address (or localhost if you’ve SSHed onto the server running the containers) to ensure it is working correctly.
- Use the /api/v1/health/heartbeat endpoint to verify that the API service is running and accessible
- Use the /api/v1/health/check_up endpoint to verify service health and its connections to other required services.
  - This endpoint requires an X-API-Key header with the value you set in SECURITY__HEALTH_CHECK_API_KEY.
  - Example: curl -H "X-API-Key: your-api-key-here" http://localhost/api/v1/health/check_up
Set Up HTTPS: The application’s API is served up on port 80 with the assumption that your infrastructure will handle HTTPS management.
You should set up something in front of the application container that receives HTTPS connections from other systems and proxies those requests to Generator. This could be a load balancer, a reverse proxy, a CDN, etc.
Configure DNS (Optional):
- Set up DNS for the HTTPS layer.
- If using a single container (not recommended), configure DNS for that container.