# Upgrading to v0.10.0

> Breaking changes in Falak v0.10.0 and how to upgrade: the new falak-ctl, the emergency kit, host databases into containers, agent updates.

Source: https://falak.sh/docs/operations/upgrade-to-v0-10/

v0.10.0 is a **breaking release**. Nobody ran Falak in production before it, so it carries no compatibility shims: host databases are no longer managed, secrets move to a new key hierarchy, and agents must match the control plane's version. Read this page before you run `falak-ctl update`.

## Before you start

1. **Back up every database you need** that Falak manages on your servers: a dump of each, kept outside Falak. Earlier versions installed PostgreSQL, MySQL, MariaDB, Redis and Valkey on the hosts; v0.10.0 forgets them (see [Databases](#databases-move-into-containers)).
2. **Back up Falak itself**: `sudo falak-ctl backup` (the update takes one too).
3. Keep `APP_KEY` unchanged until the update has finished.

## Update the control plane

The KEK file must exist before v0.10.0 starts, and the falak-ctl that runs an update is the one already installed. So install the v0.10.0 falak-ctl first; it creates the KEK during the update:

```bash
curl -fsSL https://github.com/falak-sh/falak/releases/download/v0.10.0/falak-ctl -o /usr/local/bin/falak-ctl
chmod 755 /usr/local/bin/falak-ctl
falak-ctl update --version v0.10.0
falak-ctl kek export /root/falak-emergency-kit.txt   # then store it offline and delete it here
```

During the update a migration re-encrypts every secret once: it decrypts each value with `APP_KEY` and seals it under a new data key, wrapped by the [key-encryption key](/docs/operations/security/#encryption-keys). Values already converted are skipped, so an interrupted migration can run again. There is no fallback afterwards. Export the **emergency kit** right away, as above.

If you update with an older falak-ctl, the containers refuse to start without the KEK and the update rolls back. That run has already installed the new falak-ctl, so `falak-ctl update` again then works. Backups taken before v0.10.0 restore as before: the migration converts them again.

The panel's cookies are now `__Host-falak_session`, `__Host-XSRF-TOKEN` and `__Host-remember_web` (host-only, `Secure`, `Path=/`) whenever it runs on HTTPS. `SESSION_DOMAIN`, `SESSION_PATH`, `SESSION_COOKIE` and `SESSION_SECURE_COOKIE` are gone. A plain-HTTP dev install keeps unprefixed names, and `falak-ctl doctor` warns.

## Databases move into containers

v0.10.0 runs every managed database in a [container](/docs/databases/create-databases/) and no longer manages the engines earlier versions installed on servers. Those keep running, but Falak forgets them: no backups, no references. The update's migration **refuses to run** while such databases are registered, and nothing changes:

```text
Falak v0.10 runs every database in a container and no longer manages the host databases of earlier versions …
```

1. Back up every database you need (a dump of each, kept outside Falak).
2. Set `FALAK_DROP_LEGACY_DATABASES=1` in `/opt/falak/custom.env` and run `falak-ctl update` again. The old rows, their backup history and their canvas services go; references to them fail until they point at new services.
3. Create database containers (canvas → **+ Create → Database**) and restore your dumps into them. Point the references at the new services, then remove the flag.

Backups taken before encryption can no longer be restored from Falak.

## Update every agent

From v0.10.0 the control plane **sends no commands to an agent whose version differs from its own**. Until a server's agent is updated it shows **Update the agent on &lt;server&gt;** and receives nothing — no deploys, no database operations. Update them right after the control plane: **Servers → Update all agents**, or one by one (see [Agent upgrades](/docs/servers/agent-upgrades/)).

After its agent update, each server is provisioned again automatically and gets **Docker with `live-restore`**: every server runs Docker now.

## Resource limits

Services can have memory, CPU, process, restart, log and OOM limits. The upgrade sets none: **every existing site, Compose service, worker and daemon keeps running without limits** until you set them. Only services created after the upgrade outside a production environment start with that environment's defaults (512 MB, 1 CPU, 512 processes, 20 MB × 3 log files). See [Resource limits](/docs/guides/resource-limits/).

## Disaster recovery

- `FALAK_BACKUP_PASSPHRASE` and `FALAK_BACKUP_S3_*` are no longer read from `.env`. Run `falak-ctl dr setup` with the same bucket and passphrase (it stores them in `/opt/falak/dr/dr.env`), then delete them from `.env`. Encrypted backups taken before need that passphrase.
- The cron line from earlier docs (`/etc/cron.d/falak-backup`) is replaced by `falak-backup.timer`: remove it.
- Backups are `*.fdr` now (encrypted and authenticated) and also hold `edge-pki`; restoring an older backup keeps this host's. Older `*.tar.gz.enc` backups restore from local files only, never from the bucket: take a new backup (`falak-ctl backup --upload`) after upgrading.
- Installs with several organizations: set `FALAK_DR_ORGANIZATION` (the operator organization's id) in `.env` and run `falak-ctl up`, or nobody sees the control plane's DR.

See [Disaster recovery](/docs/operations/disaster-recovery/).

## Previews

Webhooks created before v0.10.0 don't send pull request events. To use [preview environments](/docs/guides/preview-environments/), re-save the site's push-to-deploy, or add the pull request events at the provider.

## Checklist

| | |
|---|---|
| ☐ | New falak-ctl installed, `falak-ctl update --version v0.10.0` done |
| ☐ | Emergency kit exported, stored offline, deleted from the host |
| ☐ | Old host databases dumped, recreated as containers, restored, references updated |
| ☐ | Every agent updated |
| ☐ | `falak-ctl dr setup` run; `FALAK_BACKUP_*` removed from `.env`; old cron line removed |
| ☐ | `falak-ctl doctor` clean |

## Next steps
