Self-Hosted Installation

AlgoBridge runs on your own infrastructure. There are two supported deployment targets:

• AWS ECS Fargate — production-ready, auto-scaling, managed Postgres on RDS, secrets in SSM. Recommended for teams.
• Docker Compose — single-server setup. Good for small workloads, internal tools, or trying AlgoBridge before committing to cloud infra.

Both are fully automated via the @algobridge/installer CLI.

Prerequisites

Both deployment types

• Node.js 18+ on the machine running the installer
• An AWS Cognito user pool — AlgoBridge uses Cognito for authentication. See Cognito setup below.
• A verified SES sender address — used for invite and alert emails. Verify an email in SES.

AWS ECS Fargate only

• AWS CLI installed and configured: aws configure or a named profile
• An IAM user or role with the following permissions:
  • cloudformation:*
  • ecs:*, ec2:*, elasticloadbalancing:*
  • rds:*
  • cognito-idp:*
  • ssm:PutParameter, ssm:GetParameter, ssm:DeleteParameter
  • iam:CreateRole, iam:AttachRolePolicy, iam:PassRole
  • logs:CreateLogGroup, logs:PutRetentionPolicy
• An ACM certificate in the same region (required for HTTPS with a custom domain)

Docker Compose only

• Docker and Docker Compose (v2+) on your server
• A PostgreSQL database reachable from the server (or use the bundled one the installer generates)

Step 1: Run the installer

npx @algobridge/installer init

The installer asks a series of questions, then provisions everything.

ECS Fargate prompts

Provisioning takes 10–15 minutes. The installer creates a CloudFormation stack and waits for it to complete.

Docker Compose prompts

The installer writes two files to your current directory:

• docker-compose.yml — complete stack with app + PostgreSQL containers
• .env — all secrets pre-generated (session secret, encryption key, API token pepper, Postgres password)

Step 2: Start the app

ECS Fargate

The installer starts the service automatically and polls /api/health until the app is ready. When it completes, it prints the URL and your admin credentials.

Docker Compose

docker compose up -d

Run database migrations on first start:

docker compose exec app node node_modules/@algobridge/core/dist/database/migrate.js

Step 3: First login

1. Open the URL printed by the installer
2. Log in with the admin email you provided and the temporary password printed in the console (or in .env as ADMIN_TEMP_PASSWORD for Docker Compose)
3. You are required to change your password on first login
4. After login, you are the platform admin — you can invite additional users from the Admin panel

Cognito Setup

AlgoBridge uses AWS Cognito for authentication. You need a Cognito user pool before running the installer (ECS) or before filling in the .env file (Docker Compose).

Create a user pool

1. Go to AWS Cognito → Create user pool
2. Authentication providers: Cognito user pool only
3. MFA: optional (TOTP MFA is supported by AlgoBridge)
4. Required attributes: email
5. App client:
   • App type: Confidential client
   • Generate a client secret: Yes
   • Callback URLs: https://yourdomain.com/auth/cognito/callback
   • Allowed OAuth flows: Authorization code grant
   • Allowed OAuth scopes: openid, email, profile
6. Note the User Pool ID, Client ID, Client Secret, and Cognito domain

For the ECS installer, provide these when prompted (the installer stores them in SSM Parameter Store). For Docker Compose, add them to .env.

Restricting who can sign up

By default, anyone with a valid email can sign up via the login page. To restrict signups to specific domains:

# .env
ALLOWED_EMAIL_DOMAINS=yourcompany.com,partner.org

Users attempting to sign up with a different domain will see an error. Existing users are not affected. Leave unset for open registration.

Platform admin access

The first admin is created automatically from ADMIN_EMAIL on first boot. To grant admin access to additional users after setup:

1. The user must have an account (they can sign up or you can invite them)
2. Go to Admin → Users → click the user
3. Use the role selector to assign the admin platform role

Platform roles:

Custom domain and SSL (Docker Compose)

The installer does not configure a reverse proxy for Docker Compose. Place nginx or Caddy in front of the app container:

Caddy (recommended — automatic HTTPS)

algobridge.yourdomain.com {
    reverse_proxy localhost:3000
}

Then update your .env:

APP_URL=https://algobridge.yourdomain.com
COGNITO_REDIRECT_URI=https://algobridge.yourdomain.com/auth/cognito/callback
SF_REDIRECT_URI=https://algobridge.yourdomain.com/auth/sf/callback

And update the Cognito app client to allow the new callback URL.

Restart: docker compose restart app

ECS Fargate custom domain

Pass your domain and ACM certificate ARN during npx @algobridge/installer init. The installer creates an ALB listener on port 443 with the certificate attached and an HTTP → HTTPS redirect. Create a CNAME record pointing your domain to the ALB DNS name printed at the end of provisioning.

Upgrading

npx @algobridge/installer upgrade

ECS Fargate

The installer updates the ECS task definition to the new image tag, triggers a rolling deployment, and runs database migrations automatically. Downtime is zero (rolling).

Docker Compose

The installer updates the image tag in docker-compose.yml. Then on your server:

docker compose pull
docker compose up -d
docker compose exec app node node_modules/@algobridge/core/dist/database/migrate.js

Uninstalling

npx @algobridge/installer destroy

ECS Fargate

Deletes the CloudFormation stack (ECS cluster, ALB, RDS, Cognito user pool, SSM parameters). This is irreversible and destroys all data. The installer will ask for confirmation.

Docker Compose

npx @algobridge/installer uninstall
# then on your server:
docker compose down -v   # -v removes volumes (database data)

Environment variables reference

The installer generates all required secrets. If you need to customise:

Troubleshooting

Installer fails during CloudFormation deployment → Check the CloudFormation console for the stack events. Common causes: insufficient IAM permissions, or a resource limit in the target region.

App starts but login redirects to a wrong URL → Confirm COGNITO_REDIRECT_URI in your config exactly matches the callback URL registered in the Cognito app client (including http vs https and trailing slashes).

Emails not arriving (invite emails, alerts) → Confirm EMAIL_FROM is verified in SES and that your SES account is out of sandbox mode (or add recipient emails as verified identities during testing).

Migrations fail on startup → Confirm PLATFORM_DATABASE_URL is reachable from the app container and the database user has CREATE TABLE privileges. For Docker Compose, run docker compose logs app to see the error.

ADMIN_EMAIL user not created on first boot → The auto-admin is created only if no users exist yet. If the DB already has users, delete and recreate — or manually assign the admin platform role via SQL:

UPDATE users
SET platform_role_id = (SELECT id FROM platform_roles WHERE name = 'admin')
WHERE email = 'admin@yourdomain.com';

Docker Compose: node_modules/@algobridge/core/dist/database/migrate.js not found → The app image bundles the compiled core package. If you see this error, the image version may be stale. Run docker compose pull first.