Upgrading, deploying, and handing it over

Two things decide whether a framework is a help or a trap, and neither is visible on the day you start: can you take a new version without a rewrite, and can somebody else run this when you are not available.

This chapter closes Part V with both, plus the handover that the last project of your career will thank you for.

The upgrade problem, stated honestly

A framework that generates code into your project has a problem a library does not: it wrote files, you edited them, and the next version wants to write them again.

There are three possible answers, and two of them are bad.

• Overwrite
• Your edits are gone. Nobody upgrades twice
• Never touch
• Framework fixes never reach existing projects. Everybody is stranded on the version they started with
• Know which
• Track what was generated, leave what changed

grit upgrade

Files Grit wrote and you have not touched are regenerated. Files you have edited are left alone and reported, because the upgrade knows the difference: each generated file was recorded when it was written, and a file whose content no longer matches is yours.

grit upgrade --diff    # show what it would change in the files it skipped
grit upgrade --plan    # write UPGRADE-PLAN.md, a runbook for those files
grit upgrade --force   # take everything, including your edits

What an upgrade actually does

Three things, and the second is the one people do not expect.

It regenerates framework-owned files. The admin panel's shared components, the configs, the web app shell.

It repairs generated code it does not own. Your services are yours, andupgrade does not rewrite them. But a framework fix that only the generatorcarries reaches new resources and leaves every existing one broken, so there are targeted repairs that go and fix one specific thing in files the upgrade otherwise leaves alone. "A record with a price cannot be saved" is not something to leave broken on existing projects because of a rule about ownership.

It upgrades installed plugins. Left to a command of its own, nobody runs it, and a plugin fix reaches nobody.

The CLI updates itself

grit update

Releases follow channels: a plain version is stable, and a version with an-rc, -beta or -alpha suffix is not. grit update stays on stable unless you ask otherwise, which is what you want on the machine you work from.

Upgrade the CLI and the project separately, in that order, and *test a fresh project after upgrading the CLI*. A scaffold template change only shows up in something newly generated.

Deployment, in the order of effort

• One binary
• go build, copy, run under systemd. Chapter twenty five
• grit deploy
• Build, upload over SSH, configure systemd, optionally Caddy with automatic TLS
• grit deploy --railway
• Link the project, push the variables from.env, upload the API, generate a URL
• Docker Compose
• docker-compose.prod.yml, for a single machine with Postgres and Redis beside it
• A platform
• Any host that runs a container. The API is one image

Start at the top. A Go API on one server under systemd, with Caddy in front for TLS, serves a great deal more traffic than most applications ever see, and it is a stack you can hold in your head at three in the morning.

Two deployment bugs worth not repeating

Both of these were real, and both have the same shape: a path guessed from the wrong directory.

The module is not where you are standing. In a monorepo the Go module is inapps/api, and reading go.mod from the repository root finds nothing. The deploy announced itself, named the app grit-app, and then failed on "go.mod file not found".

A module's base name is not the application's name. The module isinvoices/apps/api, whose base is api, so the systemd unit, the remote directory and the binary were all called api. Two Grit projects on one server would have overwritten each other.

The checklist before a first deploy

Run these and read the output rather than assuming:

grit doctor        # configuration, dependencies, common mistakes
grit routes        # every route, and which group it is on
grit test          # all suites
grit backup        # and then actually restore it somewhere

Then the environment:

• APP_URL
• Correct, and matching the real port. Uploads build their URLs from it
• JWT_SECRET
• Generated for this environment, not copied from the example file
• Database
• Postgres, with a password that was not in a repository
• Sentinel storage
• Pointed at the real database, not the SQLite file that a redeploy deletes
• MAIL_MAILER
• A real driver, configured, and tested by sending one
• Backups
• Scheduled, and restored once to prove they work

Handing it over

The last thing a project needs is for somebody else to be able to run it. Four files, none of them long:

*README.md*: what this is, the three commands to run it locally, and where the environment variables come from.

*ARCHITECTURE.md*: the request path from route to query, and where rules live. Chapter twenty eight's assignment, kept up to date.

*RUNBOOK.md*: how to deploy, how to roll back, how to take and restore a backup, what to check when it is slow, who to call.

*DECISIONS.md*: why things are the way they are. The sort reason, the currency choice, the reason that endpoint is not cached. Six lines each, and it is the file that stops the next person undoing your work for reasons you already considered.

Where to go next

You have the language, the standard library, the framework and five applications. Three directions from here, and they are not equal.

Deeper into Go. Part VI builds things from scratch: a parser, a key-value store, a Redis, a Git. That is where the language stops being a tool you use and becomes one you understand.

Deeper into the domain. Pick the application in Part V that was closest to real work and make it genuinely production ready for one real user. The last ten percent is where the learning is.

Deeper into operations. Run something for six months. Watch it break, fix it, and write down what you changed. Nothing in a book teaches what a pager teaches.

Assignment

Commit your work with the message Deployment - Assignment One, exactly as written, so the leaderboard can score it.