Getting started

Deploying to AWS

What you are signing up for, in concrete terms. Read this before you buy if deployment effort is part of your decision.

This page describes the shape of a deployment so you can judge the effort. The exact commands, configuration files and environment variables live in the README of the repository you get access to — that is the authoritative step-by-step.

Before you start

You need Notes
An AWS account With permission to create Elastic Beanstalk environments, S3 buckets, CloudFront distributions and IAM roles.
A chosen region Pick this deliberately — it determines data residency and latency. Moving later means a migration.
A domain or subdomain Something like cms.yourbrand.com for the admin panel and API.
A TLS certificate Issue one free through AWS Certificate Manager in the right region.
Repository access The GitHub invitation sent after purchase, accepted and cloned.

The sequence

Six stages. Someone comfortable in the AWS console should expect half a day for a first environment, and considerably less for the second once they know the shape.

  1. Create the storage layer An S3 bucket for media, and the database the application will use. Note the endpoint and credentials — the application reads them from environment variables.
  2. Create the Elastic Beanstalk application and environment This is what runs the admin panel and the delivery API. Start small; you can resize later without redeploying.
  3. Set the environment variables Database connection details, the S3 bucket name and region, and the application settings listed in the README. Nothing sensitive belongs in the repository.
  4. Grant the application an IAM role Scoped to its own S3 bucket, plus MediaConvert if you intend to upload video. Resist the temptation to attach a broad managed policy.
  5. Deploy the application Push the code to the environment. On first boot you will create the initial Super Admin account and sign in.
  6. Put CloudFront in front Point a distribution at the environment, attach your ACM certificate and your domain, and set cache behaviour so published content is served from the edge.

Build staging first. Deploy a small environment, import your content into it, and point a branch of your storefront at it. You will learn everything you need for production while nothing is at stake.

How the pieces fit together

Request flow 
            your shoppers                    your editors
                  |                               |
                  v                               v
          +---------------+              +----------------+
          |  CloudFront   |              |  CloudFront    |
          |  (edge cache) |              |  (admin panel) |
          +-------+-------+              +--------+-------+
                  |                               |
                  +---------------+---------------+
                                  v
                    +-----------------------------+
                    |     Elastic Beanstalk       |
                    |  admin panel + delivery API |
                    +------+---------------+------+
                           |               |
                           v               v
                    +-------------+  +-------------+
                    |  Database   |  |  S3 bucket  |
                    |  models,    |  |  media      |
                    |  entries    |  |  files      |
                    +-------------+  +------+------+
                                            |
                                            v
                                     +--------------+
                                     | MediaConvert |
                                     |  video jobs  |
                                     +--------------+

Everything in that diagram sits in your AWS account. Nothing routes through infrastructure operated by us.

Before you go live

Work through this once the environment is up and your content is in.

  • Set an API key in Settings, and confirm an unauthenticated request is now rejected.
  • Confirm HTTPS is enforced and HTTP redirects to it.
  • Turn on automated database backups, and restore one into a scratch instance to prove it works.
  • Set CloudFront cache TTLs deliberately, then verify you get cache hits on a repeated API call.
  • Upload the largest file you realistically use and confirm it stays within the 20 MB limit.
  • Create a test entry, schedule it a few minutes out, and confirm it appears in the API on time.
  • Add your real users with the lowest role that lets them work.
  • Set up a CloudWatch alarm on environment health, and point it somewhere a human reads.

Do not skip the restore test. An untested backup is a hope, not a plan — and with self-hosting there is no vendor to fall back on.

Keeping up to date

Updates arrive in the repository. Pull them when it suits you.

Taking an update 
git fetch origin
git log --oneline HEAD..origin/main   # see what changed
git merge origin/main                 # or rebase your branch
# deploy to staging, verify, then deploy to production

If you have customised the source, keep your work on a long-lived branch and merge upstream into it. Editing the default branch directly makes every future update a conflict-resolution exercise.

Next Migrating your content Get your Contentful space into the environment you just built.