Setup

This guide takes you from zero to a running instance of AIDLC Collaborative. The platform requires AWS infrastructure for authentication, APIs, and agent execution, so setup involves both local configuration and cloud deployment.

Clone the repository

git clone https://github.com/aws-samples/sample-collaborative-ai-dlc.git
cd sample-collaborative-ai-dlc

Deploy the AWS infrastructure

Bootstrap the Terraform state backend

The bootstrap script creates an Amazon S3 bucket for Terraform state storage. Run it once per environment.

export AWS_PROFILE=your-profile-name
./scripts/bootstrap.sh dev

This creates an S3 bucket with a unique name and updates terraform/environments/dev/backend.tf with the bucket reference.

Configure the Terraform variables

cp terraform/environments/dev/terraform.tfvars.example terraform/environments/dev/terraform.tfvars

Edit terraform/environments/dev/terraform.tfvars to set your configuration.

Deploy infrastructure

./scripts/deploy-terraform.sh dev

The deployment takes 15-30 minutes. Neptune DB cluster creation takes the longest.

After deployment, configure agent authentication in the platform UI by entering either a Kiro CLI API key or Bedrock credentials (for Claude Code / OpenCode setups). Check the agent pool DynamoDB table or ECS task logs to confirm agents are authenticated and ready.

Configure provider OAuth apps

The platform integrates with external providers as code hosts (GitHub, GitLab) and issue trackers (GitHub Issues, GitLab Issues, Jira Cloud) so a sprint can be started from a tracker issue. For each provider you want to enable, register an OAuth app and paste the credentials into Admin → Tracker OAuth Apps in the deployed app.

For GitHub and GitLab a single OAuth app serves both the code host and that provider's issue tracker. Jira Cloud is a tracker only. All providers are optional — skip a section if you don't need that provider; the corresponding Connect buttons in the UI stay disabled with a hint pointing to this admin panel.

GitHub (code host + GitHub Issues)

1. Open GitHub Developer Settings → OAuth Apps → New OAuth App. Choose an OAuth App, not a GitHub App — the flow expects OAuth App semantics.
2. Set:
3. Homepage URL: https://<your-cloudfront-domain>
4. Authorization callback URL: https://<your-cloudfront-domain>/github/callback
5. Copy the Client ID and generate a Client Secret.
6. In the deployed app, sign in and open Admin → Tracker OAuth Apps → GitHub Issues. Paste both values and click Save.

GitLab (code host + GitLab Issues)

1. Open GitLab → User Settings → Applications → Add new application.
2. Set:
3. Redirect URI: https://<your-cloudfront-domain>/gitlab/callback
4. Scopes: api and read_user
5. Leave Confidential enabled.
6. Save, then copy the Application ID (Client ID) and Secret.
7. In the deployed app, sign in and open Admin → Tracker OAuth Apps → GitLab Issues. Paste both values and click Save.

Jira Cloud

1. Open the Atlassian Developer Console and create an OAuth 2.0 integration.
2. Under Permissions, add the Jira API with scopes:
3. read:jira-work
4. read:jira-user
5. offline_access (required for refresh tokens — don't skip)
6. Under Authorization, set the callback URL to https://<your-cloudfront-domain>/trackers/callback/jira-cloud.
7. Open the Settings tab of the app and copy the Client ID and Client Secret.
8. In the deployed app, sign in and open Admin → Tracker OAuth Apps → Jira Cloud. Paste both values and click Save.

Rotating credentials later is the same flow — paste new values and Save overwrites the stored secret.

The Admin UI is a wrapper around AWS Secrets Manager. To populate the secrets in your provisioning pipeline:

```bash
aws secretsmanager put-secret-value \
  --secret-id $(terraform -chdir=terraform output -raw github_oauth_secret_name) \
  --secret-string '{"client_id":"...","client_secret":"..."}'

aws secretsmanager put-secret-value \
  --secret-id $(terraform -chdir=terraform output -raw gitlab_oauth_secret_name) \
  --secret-string '{"client_id":"...","client_secret":"..."}'

aws secretsmanager put-secret-value \
  --secret-id $(terraform -chdir=terraform output -raw jira_oauth_secret_name) \
  --secret-string '{"client_id":"...","client_secret":"..."}'
```

Create users

Get the User Pool ID and create a user:

cd terraform/environments/dev
terraform output user_pool_id

aws cognito-idp admin-create-user \
  --user-pool-id <user-pool-id> \
  --username user@example.com \
  --user-attributes Name=email,Value=user@example.com Name=email_verified,Value=true

aws cognito-idp admin-add-user-to-group \
  --user-pool-id <user-pool-id> \
  --username user@example.com \
  --group-name approver

Available groups:

Set up the frontend

Install dependencies

cd frontend
npm install

Configure environment variables

cp .env.example .env

Edit .env with values from your Terraform deployment.

Deploy to S3 and CloudFront

cd ..
./scripts/deploy-frontend.sh dev

This builds the frontend, uploads it to S3, and invalidates the CloudFront cache.

Access the application

cd terraform/environments/dev
terraform output cloudfront_domain_name

Open the domain in your browser to reach the sign-in page.

Local frontend development

For iterating on the frontend locally (while connected to the deployed AWS backend):

cd frontend
npm run dev

This starts the Vite development server on http://localhost:5173.

Updating a deployment

One-time tracker-data migration (only relevant for installs with pre-#194 data)

If you're upgrading an install that ran before issue #194 (tracker provider abstraction) landed, existing projects keep working without intervention — but to bind Jira (or any future tracker) to them, their sprint and project records need a one-time backfill onto the new polymorphic shape.

Operators have two equivalent paths, both idempotent:

• Admin UI: open Admin → Tracker Migration in the deployed app. The card displays a live count of legacy projects + sprints; click Migrate all when ready.
• CLI: invoke the migrate-tracker-fields Lambda directly. Supports a dry-run for previewing.

aws lambda invoke \
  --function-name "$(terraform output -raw migrate_tracker_fields_lambda_name)" \
  --payload '{"dryRun":true}' --cli-binary-format raw-in-base64-out /tmp/out.json

Both paths share the same shared core, so the result is identical. Migration is never automatic — operators run it on demand. See Git and Tracker Integration → Migrating from legacy issue integration for full context, including why nothing is removed and the migration tooling stays deployed permanently.

Destroy infrastructure

To remove all deployed resources:

./scripts/destroy.sh dev

This permanently deletes all data including DynamoDB tables, Neptune databases, and S3 buckets. This action cannot be undone.

To also remove the Terraform state bucket (created during bootstrap):

grep bucket terraform/environments/dev/backend.tf
aws s3 rb s3://<bucket-name> --force

Troubleshooting

Terraform init fails with backend errors

Make sure the bootstrap script completed successfully and that backend.tf contains the correct bucket name.

ECS tasks fail to start

Check CloudWatch Logs for the ECS service. Common issues: missing IAM permissions, ECR image not found, resource limits exceeded.

Frontend shows authentication errors

Verify User Pool ID and App Client ID match Terraform outputs, and that the user exists in the correct group.

Provider integration not working (GitHub, GitLab, or Jira)

In the deployed app, open Admin → Tracker OAuth Apps. Each provider should show Configured; if it shows Not configured, finish the OAuth-app setup and paste the credentials. Also confirm the OAuth app's Authorization callback URL matches the values listed above for your CloudFront domain — provider apps reject mismatched callbacks at sign-in time.