What broke. The infrastructure stack failed twice before it created (an identity provider that already existed, and a certificate option that must be omitted when DNS lives elsewhere). Then the publishing job was refused by the cloud three runs in a row. The sign-in audit log showed the cause in one line: the code host had changed the format of its identity token, and our trust policy matched only the old shape. One wildcard fixed it. Then the last step of the publish failed because the role could create a cache refresh but not read whether it had finished; we stopped waiting.

What it taught us. Read the audit log before guessing. Make the build refuse to publish a page with placeholder text, because under deadline you will miss one. And keep infrastructure in a template so a fix is a line in a file, not a memory of a console click.

What is next. Connecting the forms, then moving the real domain, then turning this week’s work into a kit a student can run for another nonprofit.

What a redirect map is

A single file that says, for every old address, where it should go now:

{
  "/our-programs":        "/security/careers/",
  "/donate-today":        "/donate/",
  "/blog/summer-camp-2025": "/testimonials/seafarers-yacht-club/"
}

Ours has fifty-seven lines. The build compiles the file into the small function that runs at the edge of the content delivery network, so every old address answers with a permanent redirect (an HTTP 301) to the new page before any file is even looked up. Search engines treat a 301 as “this page moved,” and they carry the old page’s reputation to the new one. Visitors see nothing except the right page.

How to gather the old URLs

1. The old platform’s page list. Export it or copy it by hand. Include pages you plan to delete; those need redirects most.
2. Your own documents. Search your grant reports, decks, and newsletters for your domain name. Every hit is a URL someone else may still have.
3. Search engine results. Search site:yourdomain.org and page through the results. These are the addresses the public actually reaches.
4. The server log or analytics, if you have either. Anything with traffic in the last year goes on the list.
5. Old flyers and QR codes. Ask the person who makes them.

Write each one down exactly as it appears, including capitalization and trailing slashes. The map should tolerate both forms; ours strips a trailing slash before looking up the address.

How to choose the destination

For each old address pick the one new page that best answers the reason someone clicked the old link. A blog post about a past event goes to the case study or the events page, not the home page. A deleted program page goes to the nearest living program, with a sentence on that page acknowledging the change if the program really ended. The home page is the destination of last resort; a redirect there tells the visitor “we lost it.”

Rules we follow

• Every destination must end with a slash and must be a page that exists. The build checks both and refuses to publish otherwise.
• Never chain redirects. If A once went to B and B now goes to C, point A straight at C.
• Keep the map in the repository next to the content, under version control, so a change is a one-line edit anyone can review.
• After cutover, watch for 404s for a month and add a line for each one that was a real link rather than a bot guessing.

Why it matters more for nonprofits than for companies

A company can buy its way out of a broken link with advertising. A nonprofit’s reach is made of relationships and references, most of them written down somewhere by someone else. The redirect map is how you keep faith with every one of those references at once, for the cost of an afternoon and one file.

The one question. For each line: if this disappeared tomorrow, what would we lose, and could we get it back from our own files? Three answers came back. For email and donations, the answer was “a lot, and no,” so those stay. For the website, the answer was “the site, and only if we export it first,” which told us the content was not really ours. For the three forgotten subscriptions, the answer was “nothing,” and they were gone by the end of the meeting.

What it taught us. Renting is fine when the vendor does something we should not do ourselves, like running mail servers or handling card numbers. Renting is a problem when the vendor holds the only copy of something we made. The cost audit is not really about money; it is about finding the places where we have quietly given up ownership. The money follows.

What is next. The website is the biggest line where we own nothing. That is the first thing to move.

The problem the student solves

A small nonprofit pays monthly for a website builder (and often for separate forms, storage, and email tools), cannot easily edit or export its own content, and would struggle to leave. The student replaces the website with plain files the nonprofit owns, hosted on a major cloud for cents per month, published automatically from a code repository, and documented so a non-technical staff member can make changes afterwards.

Who it is for

A student who has written some HTML and run commands in a terminal. No prior cloud experience is required; the project teaches it. It fits a capstone, an internship, an apprenticeship rotation, or a self-directed portfolio project. One student can do it; two is comfortable.

What the nonprofit provides

• Ownership of its domain name and a login to wherever its DNS is managed.
• A list of every current page and which ones matter.
• About two hours of a staff member’s time per month for decisions and review, plus one hour for the handover.
• A credit card for the cloud account (expect under five dollars a month; the first year is often free-tier).

Milestones

Weeks 1–2: Discover. Inventory every page and URL of the current site. Interview the staff about what they edit and how often. Record the current recurring costs. Deliver a one-page findings memo and a proposed page list.

Weeks 3–4: Build locally. Set up the repository from the kit. Write the pages as sources. Run the build and the checker until the site passes with zero problems. Deliver a preview the client can click through on a laptop and on a phone.

Weeks 5–6: Stand up the infrastructure. Create the cloud stack from the template on a staging hostname. Connect the repository’s publishing job. Prove that a one-line edit on the code host’s website is live in minutes. Deliver the staging URL and a short screen recording of a change going live.

Weeks 7–8: Redirects, accessibility, and content review. Build the old-URL redirect map. Run an accessibility check on every page and fix what it finds. The client reviews the copy. Deliver the redirect map and a checklist of accessibility fixes made.

Weeks 9–10: Cut over. Move the apex and www hostnames to the new site without touching mail records. Monitor old URLs for a week. Deliver a cutover log: what was changed, when, and how to reverse it.

Weeks 11–12: Hand over. Write the maintenance guide in the client’s words. Record two short screen recordings: editing a page, and adding a photo. Cancel the old platform with the client. Present the before-and-after cost and a lessons-learned write-up.

Deliverables

1. The repository, with a README and a maintenance guide a non-technical person can follow.
2. The live site on the nonprofit’s domain, passing the automated checks.
3. The redirect map covering every old URL.
4. Two screen recordings (editing a page; adding a photo), each under five minutes.
5. A written case study, de-identified if the client prefers, that another nonprofit could learn from. We will publish it here with the client’s consent.

Grading rubric (100 points)

• Working system (30). The site is live on the client’s domain, publishes from the repository automatically, and passes the checker with zero problems.
• Client ownership (20). The client can make a text change and add a photo without the student, demonstrated live at handover.
• Continuity (15). Every old URL redirects; mail kept working through cutover; the cutover log is complete enough to reverse.
• Accessibility and performance (15). Every image has alt text; the site is usable with a keyboard and a screen reader; pages load fast on a phone.
• Security hygiene (10). No long-lived cloud keys anywhere; the bucket is private; the publishing identity is scoped to one repository and one branch; the student can explain why each of those matters.
• Communication (10). The findings memo, the maintenance guide, and the case study are clear to a non-technical reader.

What the student learns, in the language of a résumé

Static-site architecture and build automation; object storage and content delivery networks; TLS certificates and DNS (including the difference between a website move and a mail move); short-lived federated identity instead of stored keys; infrastructure as code; continuous deployment with automated quality gates; web accessibility; technical writing for non-technical readers; and client management with a real organization and a real budget.

Rules we ask every student to follow

• The client makes every decision that touches money, identity, or DNS. The student prepares the change and explains it; the client clicks.
• Never store a cloud access key in the repository or on a laptop. The kit’s publishing job does not need one.
• Do not cancel the old platform until the new site has served the real domain for a week.
• Write the maintenance guide before the handover meeting, then test it by having the client follow it while you watch and say nothing.

How to start

Fork the kit from our repository, read the implementation plan in this section, and find a nonprofit. If you are a student who wants a client, or a nonprofit who wants a student, write to us at hello@hackingtheworkforce.org with the subject “Site kit” and we will try to match you.

The target architecture

Five pieces, each doing one job.

• A Git repository holds the source: a build/ folder with the page sources, a redirects.json map of old URLs to new ones, an infrastructure template, and two automation workflows. The generated site is not committed; it is rebuilt on every change.
• A build script (a few hundred lines of Python) turns the sources into finished HTML. It writes the shared header, footer, navigation, and calls-to-action once, inlines the stylesheet, resizes photos, writes the sitemap, and refuses to publish any page that still contains placeholder text.
• Object storage (an S3 bucket) holds the finished files. The bucket is private; only the content delivery network can read it.
• A content delivery network (a CloudFront distribution) serves the files over HTTPS with a free certificate, rewrites clean URLs like /donate/ to the right file, and answers the old URLs with permanent redirects so nothing you ever shared goes dead.
• A publishing job (GitHub Actions) runs on every push to the main branch: build, check, upload, refresh the cache, and smoke-test three pages. It signs in to AWS with a short-lived identity token, so there are no long-lived access keys anywhere.

Phase 1: the content (half a day)

1. Inventory the old site. List every page URL. You will need this twice: once to decide what to keep, once to build the redirect map. Export any text you cannot easily recreate.
2. Decide the page list and the navigation. We went from a sprawl of pages to thirty-seven with a six-item navigation. Each page got a title, a one-sentence description, and a reason to exist.
3. Write the pages as sources, not as finished HTML. Some of ours are wireframe exports; most are short Python calls that produce a hero, a card grid, and a call to action from text. The point is that a volunteer edits sentences, never layout.
4. Mark every unknown with a visible placeholder in a fixed format, and have the build log them to a file. Ours is a bracketed tag that starts with the word SWAP and says what belongs there. The build replaces each with honest interim copy (“Pricing announced soon”) and writes the original intent to NEEDS-INPUT.md. The checker refuses to publish any page where a raw placeholder survived.
5. Build the redirect map. For every old URL, pick the new page it should land on. Ours has fifty-seven entries. This is the single most valuable file for anyone who has ever put a link in a grant report.

Phase 2: the infrastructure (two hours, once)

1. Write the infrastructure as a template, not as clicks in a console. Ours is one CloudFormation file that creates the bucket, the distribution, the certificate, the URL-rewrite function, and the deploy role. Keep it in the repository. A small script regenerates the template from redirects.json, so adding a redirect never means editing infrastructure by hand.
2. Create the stack in us-east-1 (certificates used by the CDN must live there) with the staging hostname, for example next.yourdomain.org. While it creates, the certificate service shows a validation record to add at your DNS provider. Add it; the stack waits until it resolves.
3. Point the staging hostname at the distribution with a CNAME record.
4. Connect GitHub to AWS by storing four values as repository variables: the deploy role’s identifier, the bucket name, the distribution identifier, and the site URL. The workflow reads them. Nothing secret is stored.
5. Push. The first run publishes the site to the staging hostname.

Phase 3: cutover (one hour, when ready)

1. Update the stack so the primary hostname is your apex domain and the additional hostname is www. A new certificate is issued; add its two validation records.
2. Change the site URL constant in the build (it drives canonical links and social previews) and the SITE_URL variable, and push.
3. At the DNS provider, point the apex at the distribution (an ALIAS or ANAME record, or your provider’s equivalent) and www as a CNAME. The distribution redirects www to the apex.
4. Leave every mail record alone: MX, SPF, DKIM, DMARC. Your mailboxes do not know or care where the website lives.
5. Do not renew the old platform. Keep the domain registration; it is separate from the website plan and usually cheap.

The four mistakes that cost us the most time

The identity provider already existed. If your AWS account has ever connected to GitHub before, the OpenID Connect provider is already there and a template that tries to create it again fails and rolls back. Make it a parameter and default it to “no”.

Certificate validation options without a hosted zone. If your DNS is not in Route 53, the certificate resource must omit its validation-options block entirely. Including it with an empty zone fails with an unhelpful message about a null domain.

GitHub changed the shape of its identity token. The subject claim used to read repo:Owner/Repo:ref:refs/heads/main. It now stamps numeric identifiers into it: repo:Owner@12345/Repo@67890:ref:refs/heads/main. A trust policy that matches only the old pattern is refused with “not authorized to perform sts:AssumeRoleWithWebIdentity”. Match both patterns with a wildcard condition. Check the sign-in audit log for the exact subject your run presented; it tells you in one line.

Waiting on a cache refresh you are not allowed to read. Our deploy role could create a cache invalidation but not read its status, so the “wait until done” step failed after the site was already live. Either grant the read permission or do not wait; the refresh completes in about a minute regardless.

Operating it afterwards

• A text change is an edit on the code host’s website and a three-minute wait. No tools.
• A new photo is a file dropped into a folder plus one line naming it.
• A new redirect is one line in redirects.json.
• Undo is one command, because every publish is a commit.
• Review the old-URL traffic for a month after cutover and add any redirect you missed.

What this is not

It is not a content management system with roles, drafts, and a visual editor. If your organization has many non-technical editors publishing daily, you may still want one. For a small nonprofit with a few pages that change a few times a month, this is less work, far cheaper, and entirely yours.

The full source is in our repository, and the student project brief in this section turns the plan into a semester-long service-learning project.

What was wrong

The website platform cost us a few hundred dollars a year. That is not a lot of money until you count what it bought. The site was slow to edit in any way the editor did not anticipate. Two of our volunteers could not safely change a page without breaking the layout. The 4C model pages, which we want every school to be able to copy, were locked inside a page builder that had no clean export. Old URLs we had shared in grant reports pointed at pages we could not reliably redirect. And the renewal notice arrived the same month we were deciding how to fund a participant’s training. One cohort seat is a real line item for us; the website fee was quietly competing with it.

The deeper problem was ownership. Our content lived in someone else’s database, in someone else’s format. If the price doubled, we would pay it, because the alternative was rebuilding from scratch under deadline.

What we moved to

The site is now a folder of plain HTML files in a Git repository we own. A short build script generates every page from a handful of source files, so the header, footer, navigation, donation band, and quick-exit bar are written once and appear everywhere. When someone changes a file, an automated job rebuilds the site, checks it for broken links, missing image descriptions, and leftover placeholder text, and publishes it to object storage behind a content delivery network. The change is live in about three minutes. There is no server to patch, no plugin to update, no login page for attackers to find.

Editing is simpler than it was. A volunteer can open a file in the browser, fix a sentence, and commit. If the change breaks a rule, the publish stops and the log says which line. Every version is kept, so undoing a mistake is one command.

What it costs now

Hosting the files and serving them worldwide costs us less than a dollar a month at our traffic, and the first year of the content delivery network is inside the provider’s free tier. The domain name still costs about twenty dollars a year, as it always did. The code hosting is free for a repository this size. The remaining recurring cost is the time of whoever edits the site, and that was true before.

We kept paying for three things deliberately. Email and shared inboxes, because running our own mail server is a security risk we do not want. A forms and email-sequence platform, because it routes people to the right program and we would rather spend volunteer time on people than on form plumbing. And a no-fee donation processor, because it passes one hundred percent of each gift to us. Owning the website did not mean owning everything; it meant owning the parts where renting was costing more than it returned.

What it took

About one working day, with an AI assistant doing most of the typing and a human making every decision that touched money, identity, or DNS. The build script, the infrastructure template, the redirect map for fifty-seven old URLs, and the publishing job are all in the repository. The step-by-step version is in the companion guide, and the student project brief turns the same work into a semester project a learner can do for another nonprofit.

Why we are writing this down

We train people for cybersecurity careers and we help the organizations that serve our communities stay safe online. Both of those are easier when an organization owns its technology and understands it. A nonprofit that can read its own website files can also read its own DNS records, its own access logs, and its own vendor contracts. That is the beginning of security, not an IT detail. So this section of the site will keep documenting, in public, what we run, what it costs, what breaks, and what we learn.