Week 2 – Infrastructure Setup

All repositories must be created under the github.com/incs1008 organization (private). You will receive access once your Week 1 team selection form is approved and your GitHub handles are added. After creating each repo, invite desoukya with admin permissions.

Backend

• Repo name: backend-<team>
• Examples:
  • backend-white
  • backend-blue
• Must expose GET /healthcheck returning HTTP 200 with JSON {"status": "ok"}.
• Recommended stack: Node.js Typescript. However, you can use whatever you want.

Frontend(s)

• Repo name: frontend-<team>-<app>
• Examples:
  • frontend-white-airline
  • frontend-white-travel
• Terraform publishes these apps to their own frontend domains, such as stage.white-airline.incs1008.com and stage.white-travel.incs1008.com; keep naming consistent.

In each frontend repo, copy three workflow templates: pr.yml for pull request tests, frontend-deploy-stage.yml for deploys from develop, and frontend-deploy-prod.yml for deploys from main/master.

1. Team lead submits the team lead form. Once your IAM Identity Center user is created, add the profile below to ~/.aws/config:

   [profile incs1008-team-sso]
   sso_start_url  = https://d-9967472a40.awsapps.com/start
   sso_region     = eu-central-1
   sso_account_id = 048844500727
   sso_role_name  = INCS1008Team
   region         = eu-central-1
   output         = json

2. Clone github.com/incs1008/server-config-iac and update only these files in one PR:
   1. infra/terraform/variables.tf
      • Add your team color to teams.
      • Add your team color to backend_services.
   2. infra/terraform/terraform.stage.tfvars
      • Add your backend repo to github_oidc_subjects.
      • Add your frontend repos to github_oidc_subjects.
      • Add your team color to backend_services.
   3. Add a new directory under services/<color>/
      • Copy existing services/white/ and rename to your team color.
      • Update .env.
      • Update docker-compose.stage.yml.
      • Update docker-compose.prod.yml.
   4. Add a new file under nginx/<color>.conf
      • Copy existing nginx/white.conf and rename to your team color.
      • Update stage and prod server_name values.
      • Update upstream names and backend ports.
      • Update certificate paths.
3. Stage apply: schedule a Google Meet with the Dr. Amr and run this together:

   aws sso login --profile incs1008-team-sso
   export AWS_PROFILE=incs1008-team-sso
   terraform init
   terraform workspace select default
   terraform plan -var-file=terraform.stage.tfvars
   terraform apply -var-file=terraform.stage.tfvars

4. Production apply: schedule a Google Meet with Dr. Amr and run this together:

   terraform workspace select prod
   terraform plan -var-file=terraform.prod.tfvars
   terraform apply -var-file=terraform.prod.tfvars

5. Update your PR with the new Terraform state file changes.
6. In the AWS console, verify the following were created:
   • frontend-<team>-stage-<app> buckets
   • CloudFront distributions (stage)
   • Route53 records + ACM certs for frontend domains such as stage.<team>-<app>.incs1008.com
   • incs1008-<team>-stage-queue SQS queue
   • stage.<team>.incs1008.com Route53 records
   • ECR repository team-<team> under Elastic Container Registry
7. Pause here and wait for confirmation from Dr. Amr that your TLS certificates have been created on the Lightsail server. Do not merge your PR until you receive that confirmation.

Workflow files

Copy these templates from workflow-examples into .github/workflows/ in your backend repo:

• pr.yml
• deploy-stage.yml
• deploy-prod.yml

After copying, in deploy-{stage}, set ECR_REPO and TEAM env variables (e.g., team-blue). The deploy workflows only fire when a pull request is merged into the target branch (or when you run them manually), not when the PR is merely opened.

Branch expectations

After cloning, immediately create a long-lived develop branch from main/master and make all pull requests target develop. Keep a permanent develop branch forked from main. Start every feature from develop using the pattern feature/INCS-<GH_ISSUE_NUMBER> (example: feature/INCS-1), then merge back via pull requests. Only merge develop into main/master after staging is healthy, because that promotion runs the production workflow.

Deployment flow

Staging builds team-<color>:latest, pushes to ECR, then SSHes into the server to run ./scripts/deploy-stage.sh <team>. That happens only after a PR is merged into develop.

Production uses the same repo to execute ./scripts/deploy-prod.sh <team>, promoting the latest image that already lives in ECR. Note that deploy-prod.yml fires exclusively on merges into main/master, so wait for staging to pass its health checks and verify the build in staging before promoting.

After each deploy, hit https://stage.<team>.incs1008.com/healthcheck to confirm the service restarted cleanly. You can do the same for production at: https://<team>.incs1008.com/healthcheck.