~ $ cat docs/get-started.md
Get started
Chasen puts your app on one server that you own. chasen is the CLI on your computer, and it is all you run. This page takes you from an empty server to a live app, in one command.
What you need
Section titled “What you need”- A server with Ubuntu or Debian that you can log in to with SSH, as root or as a user that runs
sudowith no password. Ports 80 and 443 are open for your apps. A small server is enough to start. - A domain for your app, with a DNS record that points to the server:
shop.example.com. The server itself needs no name. - Docker on your computer.
chasen deploybuilds the image of your app there, and sends it to the server through SSH. You need no registry and no token. If the image is already in a registry, you need no Docker either: see An image in a registry. - An app with a
Dockerfile, in a git repository. A plain website with anindex.htmlneeds no Dockerfile and no Docker.
1. Install the CLI
Section titled “1. Install the CLI”On your computer (macOS or Linux):
curl -fsSL https://chasenhq.com/cli | sh2. Deploy
Section titled “2. Deploy”cd shopchasen deploy --server root@203.0.113.5 --domain shop.example.com# chasen-server is not on this server yet. Installing it.# Setting up the server.# Installing Docker. This takes a minute or two.# Starting the proxy.# Starting the API.# The server is ready.# Logged in to ssh://root@203.0.113.5# Starting the registry of chasen on this computer. The image goes from here to the server, through SSH.# Building shop 3f9a2c1# Pulling the image from your computer, through SSH# Port 3000 (EXPOSE in the image). Health path /up. Storage /storage.# Starting shop 3f9a2c1## Deployed shop 3f9a2c1# https://shop.example.com## ✓ https://shop.example.com answers from here.This one command does everything. The first time, it also makes the machine a Chasen server:
- It logs in with your
ssh, the same way you do: your keys, your~/.ssh/config, and your known hosts apply. - It downloads
chasen-server, one binary, checks its checksum, installs Docker when the server has none, and starts the proxy and the API. It changes nothing else on the server. - It gets a login for this computer.
Then it builds the image of the current git commit with your Docker, for the CPU of the server. The image goes to a small registry on your computer (the container chasen-registry, which listens only on your computer), and the server pulls it from there through SSH. Nothing goes to the internet, and the next deploy sends only the layers that changed.
The server backs up the databases, starts the new version next to the old one, and moves the traffic when /up answers. If the new version does not answer in 30 seconds, the old one keeps the traffic, and the deploy says why. At the end, the CLI asks the address of the app from your computer and says whether it answers, or what to fix: DNS, a firewall, or the certificate.
After the first time, the command is chasen deploy. The computer knows the server, and the app has its domain. Every command goes to the server through SSH, so the server needs no name in DNS and no certificate of its own, and the only open ports are SSH and the ports 80 and 443 of your apps.
- A second app on the same server:
chasen deploy --domain blog.example.comin its directory. - A second computer:
chasen add server root@203.0.113.5logs in with no deploy. - Several servers: name the server in the command each time, or in
chasen.yml(server: root@203.0.113.5).
To test an app before it gets traffic, run chasen check.
3. The defaults, and how to change them
Section titled “3. The defaults, and how to change them”An app needs no chasen.yml when it follows the standard. Each rule has a default. When your app does something else, write the difference in chasen.yml, in the root of the app:
| What | The default | In chasen.yml |
|---|---|---|
| The name of the app | the name of the directory | name: shop |
| The port the app listens on | the EXPOSE of the image, else 8080. The app also gets it as $PORT |
port: 3000 |
| The health check | GET /up answers 200 within 30 seconds |
health: /healthz and health_timeout: 90 |
| Where the data is | the VOLUME of the image, else /storage (also at /rails/storage) |
volumes: [/app/data] |
| The memory | 512 MB | memory: 1g |
| Backups | hourly snapshots, and the live replica when the server has a bucket | backup: false, for data the app makes again at each start |
| The server | the current one: chasen servers lists them |
server: root@203.0.113.5 |
| The image | built here, and sent through SSH | image: ghcr.io/you/shop: see below |
| Settings and secrets | none | env: for settings. Secrets go in chasen secrets edit |
You do not need to guess: when a deploy fails, it says what the app did, and the line to write. Deploy has every key.
4. Add a backup bucket (optional)
Section titled “4. Add a backup bucket (optional)”A server works without a bucket: the backups then stay on its disk, and a dead server takes them with it. Add a bucket when the data matters. Any S3-compatible store works: Cloudflare R2, Backblaze B2, Hetzner, or S3.
chasen bucket --endpoint https://<your-store> --name chasen-backups --access-key-id <id># Secret access key:The server creates the bucket when it does not exist, and tests it before it saves the settings. Then the snapshots go to the bucket too, and the live replica starts.
The setup I recommend
Section titled “The setup I recommend”Two free services make a server much harder to attack, and Chasen needs no setting for either of them:
- Cloudflare in front of your apps. Turn the proxy on for the DNS records of your apps, and set SSL to Full (strict). Visitors see the addresses of Cloudflare, not the one of your server, and Cloudflare takes the load of a traffic spike. Then let ports 80 and 443 of the server take traffic only from Cloudflare. Domains has the details.
- SSH only from your private network. Install Tailscale on the server and on your computer: it is the easiest. To run the network yourself, use Headscale or NetBird, which are open source, or plain WireGuard. Then close SSH to the internet.
chasen deployworks the same, with the name of the server in the network:chasen deploy --server root@shop-server.
With both, the internet sees ports 80 and 443 through Cloudflare, and nothing else. chasen alerts tells you what is still open. Keep SSH off the internet has the firewall lines.
Leave out the base domain too. With one, the API answers on port 443 to anyone who finds it. Without one, the CLI and CI reach the server through SSH, from the private network. Keep the API off the internet has the steps.
An image in a registry
Section titled “An image in a registry”The default needs no registry. Use one when:
- The server is on the web, with a base domain and a token: GitHub Actions. There is no SSH to send the image through, so the image goes to
ghcr.io/<owner>/<repository>, from the git origin of the app on GitHub. Deploy from GitHub Actions has the steps. - You want the image in a registry anyway. Name it in
chasen.yml, and Chasen pushes it there, also through SSH:image: ghcr.io/you/shop, orimage: you/shopfor Docker Hub. No tag: the tag is the commit. - The image is not yours to build: an app that someone else releases, and you have no code of. Make a directory with only a
chasen.yml, and noDockerfile:
name: analyticsimage: someone/analytics # deploys the newest one. For one version: chasen deploy --tag 2.7.6port: 8080volumes: [/app/storage]chasen deploy in that directory pulls the image on the server. It builds nothing, so it needs no Docker on your computer.
The login to the registry. A public image needs none. For a private one, Chasen uses the login that Docker already has, and sends it with the deploy, so the server can pull:
docker login ghcr.io# Username: your GitHub name# Password: a classic GitHub token with the write:packages scope (github.com/settings/tokens)If you use the GitHub CLI, this does the same with no token to copy: gh auth login -s write:packages. In CI, Chasen takes GHCR_TOKEN or GITHUB_TOKEN.
What comes next
Section titled “What comes next”| You want | Command |
|---|---|
A second address for the same app, like www.shop.example.com or an old name |
chasen domains add www.shop.example.com |
| See what runs | chasen status, chasen logs, chasen history |
| Give the app a secret | chasen secrets edit, then chasen restart |
| Change a setting | Edit chasen.yml, then chasen restart |
| Go back to the version before | chasen rollback: in seconds, with the same data. chasen rollback <version> goes to one of the last 5 |
| Restore the data | chasen backups, then chasen restore |
Deploy on every git push |
Deploy from GitHub Actions |
A base domain, and an address on the web (optional)
Section titled “A base domain, and an address on the web (optional)”Give the server a base domain when you want two more things:
- A name for each new app with no flag. With the base domain
example.comand a wildcard DNS record (*.example.compoints to the server), a new app gets<app>.example.com. - The API on the web, at
https://api.example.com. Then a computer needs no SSH access to the server: it logs in with a browser, and CI deploys with a token.
The cost: the API is on the internet, and chasen alerts warns about it. I recommend SSH from a private network instead: Keep the API off the internet.
Run this on the server, as root:
chasen-server setup --domain example.comThen, on a computer:
chasen add server example.com# Open this page to log in:# https://api.example.com/oauth/device?user_code=BCDF-GHJKOpen the page, check the code, and type the token of the server (chasen-server token prints it). The CLI then has a token of its own. The SSH way keeps working next to it.
If the firewall of the server lets in only the addresses of Cloudflare, every name of the server must go through Cloudflare: turn the proxy on for the wildcard record too.
Limits to know
Section titled “Limits to know”- One container for each app, with 512 MB of memory unless
memory:inchasen.ymlsays more. One more container for its background jobs, whenjobs:names its command. Cron jobs run in the web container. - SQLite only. Uploaded files persist across deploys, but they have no backup yet.
- The build is for the CPU of the server,
amd64orarm64. When your computer has another one, the build runs under emulation and takes longer. setupdoes not harden the server.chasen alertsreports what is missing, with the fix: SSH with keys only, a firewall, and security updates.
Updates
Section titled “Updates”Chasen updates itself on your server. Each night, in the quiet hour of the server (03:00 until one is known), at a random minute of it, a timer runs chasen-server update. It updates Chasen and its proxy, not the operating system:
- It compares the checksum of the newest release with the binary that runs. When they are the same, the binary stays.
- It keeps the old binary as
chasen-server.previous, installs the new one, and starts the API again. Your apps do not restart. - When the new API does not answer in 30 seconds, it puts the old binary back.
- Each release of Chasen names the version of the proxy (kamal-proxy) that it runs. When the proxy of the server is another one, the update swaps it. During the swap, a few seconds, a new visitor gets no answer at first, and their browser sends the connection again a second later, to the new proxy: a pause, not an error. A request that runs during the swap, like an upload, is cut. The routes and the certificates stay. When the new proxy does not answer with every route, the old one starts again.
- It never interrupts a deploy: it waits for the next night.
- Then it moves the timer to the quiet hour of the server: the hour with the fewest requests in the last week, from the log of the proxy.
chasen-server update # update nowchasen-server proxy # the version of the proxy, and the one of this releasechasen-server proxy update # swap the proxy nowsystemctl list-timers chasen-update.timer # when the next run isTo turn the nightly update off, run chasen-server settings auto_update off. chasen-server settings shows what is set.
The CLI updates itself too. Once a day chasen looks for a newer release. When there is one, it installs it after your next command that works, checks its checksum, and says so in one line. chasen update installs it now. It never updates in CI, where a program that changes between two commands is a surprise. To turn it off, set CHASEN_NO_UPDATE_CHECK=1. When chasen is in a directory that needs sudo, like /usr/local/bin, it tells you to run sudo chasen update instead. The install script puts it in ~/.local/bin when that is on your PATH, so it needs no sudo.
The operating system is yours. Chasen does not update it and does not reboot it: it sets nothing there. We recommend that you turn on automatic security updates yourself, and let the server reboot at night when an update needs it. On Ubuntu:
apt-get install -y unattended-upgradescat > /etc/apt/apt.conf.d/52auto-reboot <<'CONF'Unattended-Upgrade::Automatic-Reboot "true";Unattended-Upgrade::Automatic-Reboot-Time "04:00";CONFA reboot is safe: Docker starts at boot, and the proxy, the API, and your apps start again by themselves. It costs about one minute of downtime.
You can turn the automatic reboot off. Do this when one minute of downtime at night is not acceptable, and you want to choose the moment yourself:
echo 'Unattended-Upgrade::Automatic-Reboot "false";' > /etc/apt/apt.conf.d/52auto-rebootUbuntu still installs each security update. A new kernel then waits on the disk: the server runs the old kernel, with its known holes, until you reboot. So check and reboot yourself:
cat /var/run/reboot-required # the file exists when a reboot is waitingrebootTo move the reboot to another hour, keep "true" and change Automatic-Reboot-Time.
The server knows its quiet hour. The proxy logs each request, so the server can count them. This command prints the hour of the day with the fewest requests to your apps in the last week, in the time zone of the server:
chasen-server quiet-hour # 03:00Put that hour in Automatic-Reboot-Time. The command needs one full day of log before it answers.
chasen alerts tells you when the server does not install its security updates, and when an update waits for a reboot for more than a day.