Server Administration

Manage your Formlander server - CLI, backups, logs, and troubleshooting

Everything you need to run Formlander on your server.

Install

curl -fsSL https://formlander.com/install | sudo bash

The installer asks for your domain, then installs Docker, starts a reverse proxy (kamal-proxy) with automatic HTTPS, and runs Formlander behind it. Several apps can share one server: each gets its own domain behind the same proxy.

At the end, the installer prints the admin email ([email protected]) and a random first password. If you lose it, read it on the server:

sudo cat /var/matcha/formlander/storage/initial-admin-password

Change the password in Settings after you sign in. The file is removed when you do.

Upgrading from an older version: if your admin still used the old default password formlander, Formlander replaces it with a random one on start. Read the new one from the file above.

Commands

Command	What it does
`formlander install`	Install Formlander
`formlander update`	Back up the database, pull the latest image, and redeploy with no downtime
`formlander reload`	Redeploy with the current configuration
`formlander restore-db`	Pick a backup and restore it
`formlander change-admin-password`	Set a new admin password without the old one
`formlander check`	Check the server’s security settings
`formlander version`	Show the version

Run them with sudo.

Where things live

/etc/matcha/config.yml              # Domain, image, and environment for each app
/etc/cron.d/formlander-update       # Nightly update
/var/matcha/formlander/
├── backups/                        # Database backups
├── logs/
│   └── update.log                  # Output of the nightly update
└── storage/
    ├── formlander.production.db    # Database
    ├── initial-admin-password      # First password, until you change it
    ├── logs/                       # App logs
    └── uploads/                    # Files sent with submissions

Configuration

Each app has an entry in /etc/matcha/config.yml. Add environment variables under env, then run sudo formlander reload:

apps:
  formlander:
    image: karloscodes/formlander:latest
    domain: forms.example.com
    env:
      FORMLANDER_SESSION_TIMEOUT_SECONDS: "86400"

Logs

sudo docker logs -f $(sudo docker ps -qf name=formlander)   # App output
sudo tail -f /var/matcha/formlander/logs/update.log         # Nightly updates

The container is named formlander or formlander-next. Each deploy starts the other name, so the old one keeps serving until the new one is healthy.

Database

sudo sqlite3 /var/matcha/formlander/storage/formlander.production.db

Backups

Automatic backups

Every update backs up the database first, so you get one backup per night. The last 3 backups are kept in /var/matcha/formlander/backups/.

Restore one any time with sudo formlander restore-db.

Off-server backups

These backups live on the same server. If the server dies, the backups die with it.

Pick one off-server strategy:

Strategy	Effort	Protection
VPS snapshots	Low	Your provider handles it. Turn on weekly snapshots in your VPS dashboard.
rsync to another server	Medium	A cron job copies the backups every night.

VPS snapshots are the simplest. Most providers (Hetzner, DigitalOcean, Linode) offer them for a few dollars a month.

rsync example (daily at 2 AM, before the 3 AM update):

0 2 * * * rsync -az /var/matcha/formlander/backups/ user@backup-server:/backups/formlander/

Automatic updates

Every night at 3:00 AM, server time, formlander update:

updates the formlander command itself,
backs up the database,
pulls the latest image and redeploys with no downtime.

If you can’t wait for the night, run sudo formlander update yourself.

Server requirements

Resource	Minimum
CPU	1 vCPU
RAM	512MB
Storage	10GB SSD

Network: ports 80 and 443 open, for Let’s Encrypt and HTTPS.

Troubleshooting

Problem	Fix
The site doesn’t load	`sudo docker ps` shows `formlander` (or `formlander-next`) and `matcha-proxy`. Check the app output with the logs command above.
SSL errors	Check that DNS points to the server and ports 80 and 443 are open.
A form says “origin not allowed”	Add the site’s domain to the form’s Allowed Origins.
Lost admin password	`sudo formlander change-admin-password`

Uninstall

sudo rm /etc/cron.d/formlander-update
sudo docker exec matcha-proxy kamal-proxy remove formlander
sudo docker rm -f $(sudo docker ps -aqf name=formlander)
sudo rm -rf /var/matcha/formlander      # Deletes your data. Copy the backups first.
sudo rm /usr/local/bin/formlander

Then remove the formlander entry from /etc/matcha/config.yml. If no other app uses the proxy, also run sudo docker rm -f matcha-proxy.