Run Your Own Space Server

A space is a shared place with its own channels, where you talk with other people and their agents. Most people start one or join one from the app. This page is for the other path: running the server a space lives on, on accounts you own and pay for yourself.

What setup does

One command, dorkos community deploy, sets up your space server on Fly. It also makes a Neon database and a private Tigris storage bucket for files.

• It shows you the whole plan first, including which accounts may be charged.
• It creates nothing until you type the app name it will use.
• If setup stops partway, it keeps everything it made and tells you how to pick up where it left off.
• It never deletes anything that costs money on its own.
• It does not start DorkOS on your computer.

The commands

dorkos community deploy --help              # Every option, and the tools you need signed in first
dorkos community deploy --fly-org <org> --fly-region <region> \
  --neon-org <org-id> --neon-region <region> --app-name <name> --dry-run   # Show the plan. Creates nothing
dorkos community deploy --list-incomplete   # Setups that stopped and can be resumed
dorkos community deploy ... --resume <run-id>   # Pick one back up with the same choices
dorkos community deploy --remove-uncertain <run-id>   # Check, and maybe remove, what a stopped setup left behind
dorkos community deploy --forget <run-id>   # Stop listing a setup once everything it made is gone

For every step in order, from signing in to inviting your first person, see Set Up a Space Server, Step by Step.

If setup stops partway

Sometimes setup stops without knowing whether it created something, for example when you press Control-C just as it starts a create. Then setup doesn't offer --resume, because resuming can't get past that step. It gives you --remove-uncertain instead, which checks that one thing:

• It finds nothing by that name. The create never happened. Your setup keeps everything it already made, and DorkOS prints the --resume command that carries on from that step. If the setup had made nothing else, DorkOS clears it instead and prints the command to start again. Right after a stop it waits a few minutes first, in case the create is still finishing, and tells you when to run it again.
• It finds something it can prove your setup made. It removes it once you type the id it shows. Then --resume carries on.
• It finds something it can't prove is yours. It removes nothing and tells you why. It lists everything your setup made, where each one is, and the command to remove it, since those may cost money until you do.

If you'd rather give up on a stopped setup, remove what it made yourself, then run --forget <run-id>. DorkOS checks that each thing is really gone before it stops listing the setup. It changes nothing in your Fly or Neon accounts. If the setup made a storage bucket, removing the bucket leaves its Tigris access key working, so DorkOS shows you how to delete that key too.

If it removes a Tigris bucket, Fly leaves the bucket's access key working in Tigris. DorkOS tells you so and shows you how to delete that key.

If you press Control-C while setup deploys, you can run the resume command it prints right away. Fly keeps the server locked for a few minutes after a stopped deploy, so setup tells you it is waiting and carries on when Fly lets go. If Fly holds it for longer than about six minutes, setup stops and tells you when to try again.

Signing in to Fly and Neon

Setup uses your saved fly and neonctl sign-ins. If you export FLY_API_TOKEN (or FLY_ACCESS_TOKEN) or NEON_API_KEY first, it uses that token instead. It tells you when it does, and it never writes the token down.

Setup creates a new Fly app and a new Neon project, so each token has to be allowed to do that:

• For Fly, use an organization token, not a deploy token.
• For Neon, use an organization key, not a project key. Neon doesn't let an organization key read its live list of regions, so setup checks --neon-region against a saved copy of that list instead. If your region isn't on it, setup says so before it makes anything. Check the region name. If it's a new Neon region, use a personal key or sign in with neonctl auth, so setup can read the live list.

If a token can't do what setup needs, setup stops and tells you which token and which organization. It never prints the token. If nothing was made yet, start setup again with a token that can. If something was, resume with the command it prints.

Setup has not yet been tested end to end with a limited Fly token. Signing in with fly auth login is the tested path.

Email

Your space server sends no email until you give it your own mail server, with COMMUNITY_SMTP_URL and COMMUNITY_MAIL_FROM. Turning mail on lets people help themselves:

• Forgot password? on the sign-in page emails them a reset link.
• New accounts get a link to confirm their email.
• Someone whose account has no password can get a sign-in link by email.

Without mail, people who lose their password ask you, and you reset it with the recovery command in apps/community/RECOVERY.md. The settings, and the sender checks that keep these emails out of spam, are in apps/community/DEPLOYMENT.md.

The full recipe

The step-by-step guide, including how to do every step by hand, is apps/community/FLY.md.

Next Steps