Skip to main content

New Customer Setup

Topic:

  • Decisions:
    • Domain name (SERVER_DOMAIN, PREVIEW_DOMAIN, and HOSTED_ZONE if DNS zone is different than SERVER_DOMAIN) (Customer)
    • Will AWS be managing the service certificates? (Recommended) (Customer)
    • Allocate a VPC to run the service (one per AWS account), and set any security groups for reaching that VPC (Customer)
    • If service can’t be on internet, SST changes may be required (Bike4Mind)
    • Support email address (Customer)
    • Mail from address (Customer)
    • Where to run Mongo (Customer)
  • Fork b4m-core repository (Coordinated)
    • Create new repository within customer org: b4m-core (Customer)
    • Push to new repository (Bike4Mind)
  • Fork main repository (Coordinated)
    • Create a new local main branch for customer main: git checkout -b customer/main (Bike4Mind)
    • Update b4m-core in .gitmodules to reference forked b4m-core repo, commit on branch customer/main (Bike4Mind)
    • Create new empty repository within customer org: bike4mind (Customer)
    • Add remote: git remote add customer git@github.com:Customer/bike4mind.git (Bike4Mind)
    • Push, mapping local customer/main to main on customer remote: git push -u customer customer/main:main (Bike4Mind)
  • Create new AWS account, configure services (Customer)

    Create account according to instructions in https://v2.sst.dev/setting-up-aws, skipping the last section “Configure SST”

    Once accounts are created, be sure to logout and log back in under the proper sub-account/organization for resource creation

    • Route53 (sub-)zone, based on SERVER_DOMAIN and HOSTED_ZONE
    • Create VPC for services, store id (vpc-1234adfe) in $VPC_ID - note: cannot use the default public VPCs in the account
      • Select ‘VPC and more’, using defaults except:
      • Ensure IP space is not in conflict if needing to communicate with other networks
      • Enable NAT gateway to corporate standards (in 1 AZ vs the recommended 1 per AZ)
    • SES, based on domain name selection
      • Get Started, enter email address and domain
      • Verify Sending Domain, updating records in DNS (seems to be manual, even when on Route53?)
      • Once verified, do Request Production Access
      • Then SMTP Settings > Create SMTP Credentials
      • Capture credentials to MAIL_USERNAME, MAIL_PASSWORD
    • Create an ECR called bike4mind/subscriber-fanout
    • DocumentDB, if applicable
      • Instance-based cluster
      • Select sizing per organization need
      • Specify a password (don’t use secrets manager)
      • Select other options as desired
    • Bedrock: Enable relevant (or all) models in us-east-1 (not your local AZ!)
    • Quotas:
      • Ensure Lambda’s ‘Max Concurrent Execution’ quota is at least the default (1000) - this is an account-wide quota that may only be available in US-EAST-1 (Customer)
      • AWS Roles Per Account (available only in us-east-1): set to 3000, especially in development accounts where we’ll run numerous stages (Customer)
  • Create mongo service (Customer)
    • Exact instructions vary - if using DocumentDB, see steps in AWS section above
    • Get connection string, store in MONGODB_URI secret
  • Do initial SST bootstrap: npx sst bootstrap --profile $aws_credentials_profile (Customer)
  • Create new Seed account (Customer)
    • Add a new App (Customer)
      • Link the cloned bike4mind GitHub organization. If naming specific repositories, be sure to include both bike4mind and b4m-core forks
      • Add a service: / of type SST, service name bike4mind, click Add Service
      • “Help me create an IAM role” for both dev and prod, > Create an IAM Role using CloudFormation
      • Ensure the right AZ is selected
      • Check the Acknowledgment under Capabilities, then Create Stack
    • Configure app settings (Customer)
      • Go to dev env, click Show Env Variables, enter variables as per below
        • ECR_CACHE_REPO: Docker repo for ECR, e.g. $account_id.dkr.ecr.$aws_region.amazonaws.com/bike4mind/subscriber-fanout
        • SERVER_DOMAIN: The domain name suffix that will run the app, e.g. app.$SERVER_DOMAIN
        • PREVIEW_DOMAIN: The domain name suffice to use for preview builds in development; we'll prepend app.pr$number. to this domain when making PR/preview branches
        • HOSTED_ZONE: The DNS zone (in Route53) that contains $SERVER_DOMAIN, if not the same
        • APP_CERT_ARN: required if AWS isn’t generating the certificates on its own
        • VPC_ID: A VPC to run certain services - if none given, it will create one if needed. Note that this does not affect whether the application load balancers are public-facing
        • FAB_FILES_BUCKET_NAME: If specified, the bucket that will contain Knowledge Files. If not specified, application will create its own (recommended)
        • GENERATED_IMAGES_BUCKET_NAME: If not specified, application will create its own (recommended)
        • APP_FILES_BUCKET_NAME: If not specified, application will create its own (recommended)
        • ENABLE_BUCKET_VERSIONING: true/false
        • ENABLE_WARMING: true/false
        • Automatically set in Seed: SEED_APP_NAME: the installation name, something customer-specific is recommended
        • Automatically set in Seed: SEED_STAGE_NAME: production and dev are meaningful
        • Automatically set in Seed: CI: true for CI environments
  • Create secrets for each stage (Customer)
    • MONGODB_URI: from Mongo service, substituting %stage% where needed
    • Secrets
      • SESSION_SECRET: arbitrary
      • JWT_SECRET: arbitrary
    • Google login
      • GOOGLE_CLIENT_ID
      • GOOGLE_CLIENT_SECRET
    • GitHub login
      • GITHUB_CLIENT_ID
      • GITHUB_CLIENT_SECRET
    • Okta organization login
      • OKTA_AUDIENCE
      • OKTA_CLIENT_ID
      • OKTA_CLIENT_SECRET
    • PDFJS_EXPRESS_VIEWER_KEY
    • DEFAULT_THEME
    • Stripe
      • STRIPE_SECRET_KEY
      • STRIPE_PUBLISHABLE_KEY
      • STRIPE_WEBHOOK_SECRET
    • Email-related
      • SUPPORT_EMAIL
      • MAIL_FROM
      • MAIL_HOST
      • MAIL_PORT
      • MAIL_USERNAME
      • MAIL_PASSWORD
    • SalesForce (Polaris)
      • SF_CONSUMER_KEY
      • SF_CONSUMER_SECRET
      • SF_USERNAME
      • SF_PASSWORD
      • SF_SECURITY_TOKEN
      • SF_INSTANCE
  • Do an sst build from a local tree, to update sst’s zone list (Customer)
    • SERVER_DOMAIN=$server_domain HOSTED_ZONE=$hosted_zone VPC_ID=$vpc_id pnpm sst build --profile $aws_profile --region $aws_region --stage dev
    • Prune entries from cdk.context.json and commit to forked main branch
  • Push branch to run deploy from Seed (Customer)