feat: outpost cli & redis migrator & startup logic

[alexluong]

This PR implements a few significant improvements:

1. improve CLIs (using urfave/cli)
2. move the Redis Migration CLI as part of outpost release for easy migration steps (no need to clone outpost repo)
3. improve Redis Migrator logic (simplify & support startup flow)

CLIs

This PR treats outpost binary as a CLI with flags, help, and a few subcommands. Each subcommands is its own CLI binary.

• outpost is the main CLI binary which is a lightweight wrapper CLI which execs other subcommand CLI
• outpost serve runs outpost-server binary which is the main Outpost service
• outpost migrate redis runs the Redis Migrator

With this setup, when we release outpost the Docker image or the binary (binaries), they can run the Redis migration script directly. Without that, the user will have to clone our repo or copy and paste some sort of shell script for this migration logic.

Redis Migrator

Building off of the previous Redis migrator logic, I'm cleaning things up a bit. The main flow is still roughly the same:

# check if there's pending migration
outpost migrate redis plan

# apply the migration
outpost migrate redis apply --yes

# verify the migration applied successfully
outpost migrate redis verify

# clean previous data (if necessary)
outpost migrate redis cleanup

Beyond the migration flow, we also introduce an init command which can be run as part of the startup script

# startup command
outpost migrate redis init --current && outpost serve

For fresh installation, the init script will mark all previous migration as "applied". For existing installation, the --current flag will exit with status 1 if Redis is not up-to-date, forcing user to run the migration script to avoid user running an Outpost version with unsupported data.

The Redis Migrator has lock mechanism for mutation as well as the init script to account for cases where multiple nodes are starting up at the same time (potentially in a fresh installation).

PR TODOs

This PR isn't quite ready just yet. The code logic is there but we need to improve the build / goreleaser workflow to support this approach.

TODOs

• update goreleaser to outpost multiple binaries
• include redis init in the startup script for final build
• QA the built Docker image
• deprecate / remove the unused Dockerfile, closing chore(build): Copy go mod files first to leverage Docker layer cachin… #482, fix(build): include CA certificates in Docker image #483 (will do this in a separate PR)
• review logging output & use proper logger
• write /guides/migration post
• record workflow demo video

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
outpost-docs	Ready	Preview	Comment	Sep 29, 2025 6:59pm
outpost-website	Ready	Preview	Comment	Sep 29, 2025 6:59pm

[alexbouchardd]

Solid approach! 🙏

[alexbouchardd]

Shouldn't the migrate command abstract the underlying services? As in, if there's both a postgres and redis migration to run, shouldn't we just expose migrate and have the CLI handle which services need to be migrated. Same goes for migrate redis init -> migrate init. Or really just init

[alexluong]

Shouldn't the migrate command abstract the underlying services?

@alexbouchardd This is something I thought about as well but I think it's easier to keep it separate for now, mainly for delivery & timeline perspective.

The SQL migration logic is there too but it's currently handled as part of the startup flow. And also for Redis, since we're not supporting zero-downtime migration yet so the SQL & Redis migration logic are not as easily abstracted.

How important should we treat this migration abstraction? Or can we move forward with this approach in the PR and get back to the SQL migration later when it's more appropriate?

[alexbouchardd]

I just think we shouldn't make the user think about which component needs to be migrated and in which order. It's really our responsibility to orchestrate the migration. If we go the migrate redis route, then we'd eventually deprecate it. Might as well just do migrate and only migrate Redis for now if it's the only thing supported until 1.0?

[alexluong]

@alexbouchardd that could work, so "outpost migrate" will simply do exactly what "outpost migrate redis" is doing now. If we want to introduce SQL to it later we can but the interface will remain mostly the same.

[alexbouchardd]

Yeah. We'll build on it until it's solid for ^1.x releases

[leggetter]

@alexluong - should this be a draft? Based on the discussions above I'm assuming addition work is planned?

[alexluong]

@alexluong - should this be a draft? Based on the discussions above I'm assuming addition work is planned?

@leggetter yes, please see the TODOs at the end. The main logic is there but I got a few refactors pending, that's all.

Pushed a few commits just now but got a few more coming, one of which is the logger piece which involves quite a bit of refactor, but UX-wise it should remain the same

[alexluong]

Sharing the final workflow demo video of everything, including mention of

• migration tool
• local build command
• full QA flow, using built images, from running previous version, failed upgrade attempt (because of pending migration), steps to run the migration, and final upgrade step

I think this PR is now ready to go. Please check this out and let me know if we still need anything else.