Theme

Deploy Mimeo

Mimeo is a standard Rails application. Any host that runs Rails apps works when configured for the requirements below. Hatchbox on DigitalOcean is the recommended starting point and current favorite: Hatchbox manages deployment on a server in your own DigitalOcean account.

Other common options include AWS EC2, Hetzner Cloud, and Linode. The same application requirements apply; the deployment controls differ. Mimeo's default database is a local SQLite file, so choose persistent disk and a single application server rather than disposable storage or a multi-server database setup.

What the app needs

Keep every process that accesses SQLite on the same server and the same persistent database path. A platform that replaces containers or releases must mount or link persistent storage into each release; an ephemeral filesystem is not sufficient.

1. Put your download in a private Git repository

Download the latest Mimeo and Mimeo Manager ZIPs from the License page in your account. Both use the same version per release. Deploy the Mimeo Rails application; keep Mimeo Manager for your local agent workspace.

Extract the Mimeo ZIP, including hidden files. Create an empty private repository in your own GitHub account. In a terminal inside the extracted app folder:

git init
git add .
git diff --cached --stat

Review the staged files before committing. The app's .gitignore excludes environment files, Rails key files, and runtime storage. Check that no credentials, database, subscriber data, or uploads are staged. Then commit and push to your own repository, replacing YOUR-ACCOUNT and the repository name:

git commit -m "Initial Mimeo release"
git branch -M main
git remote add origin [email protected]:YOUR-ACCOUNT/my-mimeo.git
git push -u origin main

This is your application repository. Mimeo Manager is a separate repository for email definitions and media, not the Rails deployment source.

2. Create the DigitalOcean server through Hatchbox

Create your Hatchbox and DigitalOcean accounts, then connect DigitalOcean to Hatchbox. In Hatchbox, create a cluster and add one server on DigitalOcean. Select an available region and server size with capacity for Rails, its job workers, Node rendering, and asset builds.

Assign Web and Cron roles to that same server. Hatchbox uses the Cron role to run Rails migrations once per deployment; it is not where you add Mimeo's recurring email jobs. Keep database work on this server because SQLite is local. No separate database server or database role is needed for Mimeo's default setup.

Use Hatchbox's first-deployment guide for the account and cluster screens. DigitalOcean's Droplet documentation explains regions, sizes, SSH access, and server backups; let Hatchbox create the server for this walkthrough rather than creating a second one manually.

3. Create the app and prepare persistent storage

In Hatchbox, choose New App, connect your private GitHub repository, and choose its deployment branch and cluster. Confirm the Ruby and Node versions above. Leave automatic deployment off until the first setup is verified.

Keep the app's SQLite configuration in config/database.yml. There is no external database to attach and no database password to enter. Do not add a DATABASE_URL for another database or the separate Solid database URLs shown in generic Rails tutorials; this app already shares one primary database.

Ensure storage/ is shared across Hatchbox releases and writable by the app before using the instance. It must not be replaced by an empty release-local directory on deployment. After the first deploy, inspect the deployed directory and confirm its persistent target before importing any data.

The app's bin/rails db:prepare command can create and migrate the production database. Hatchbox's standard Rails deployment runs migrations; verify their success in the deploy log. Production seeds deliberately create neither demo data nor an owner account.

4. Set environment variables and secrets

Generate a unique installation secret in a private terminal and save the output in your password manager. Never commit it:

ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'

Open the app's Environment settings in Hatchbox. Use these values for a fresh installation:

For this fresh-install SECRET_KEY_BASE setup, leave RAILS_MASTER_KEY unset and keep config/master.key and config/credentials/production.key out of the deployed files. The application derives its encryption keys from secret_key_base; provider and media credentials are entered later in the app, not read from the packaged Rails credentials.

If you manage your own encrypted Rails production credentials instead, RAILS_MASTER_KEY must match your own config/credentials/production.yml.enc, containing your installation's secret_key_base. A random master key cannot decrypt an existing encrypted file. Use one deliberate secret configuration, not a mix of unrelated keys.

Keep the installation's secret_key_base stable across deploys and restores. Changing it invalidates signed links and sessions and makes stored provider, storage, and SMTP credentials unreadable. Back up the secret separately from the database. Do not set SECRET_KEY_BASE_DUMMY on the running app.

Optional rendering settings:

Resend/Postmark API keys and webhook secrets belong in the in-app sending wizard. R2/S3 keys belong under Settings → General → Storage & media. You do not need those service credentials just to deploy and create your owner account.

5. Configure the processes

Hatchbox creates the Rails web process during its first deployment. Keep it on the Web server and use the app's Puma configuration so Solid Queue starts with it.

Under Processes, add the renderer:

Hatchbox may also auto-create a bin/jobs process when it detects Solid Queue. Inspect the process list after the first deploy and stop/remove that additional process for this configuration: Mimeo's Puma plugin already starts the queue supervisor. Do not add duplicate minute-by-minute cron jobs; the recurring schedule runs through Solid Queue.

See Hatchbox's Rails deployment reference for its automatic build and process behavior. Its generic multi-database examples do not apply to Mimeo's single SQLite database.

6. Add your domain and SSL

In Domains & SSL, add your app hostname, such as mimeo.example.com. At your DNS provider, point that hostname's A record at the server's public IP. Allow Hatchbox's Caddy server to issue and renew the HTTPS certificate once DNS resolves.

Follow Hatchbox's SSL guide if certificate issuance fails. Mimeo's production configuration expects HTTPS behind a TLS-terminating proxy; do not work around certificate problems by exposing the app over plain HTTP.

This is the host where you sign in. When the sending wizard later asks for a separate link hostname on your sending domain, add that hostname to Hatchbox's app domains and SSL as well, then add the DNS record shown by Mimeo. A CNAME alone does not configure the web server to serve the additional hostname. See Domains & senders.

7. Deploy and check the installation

Choose Deploy and inspect the logs. Confirm that dependency installation succeeds, assets compile, migrations run on the server with the persistent SQLite file, and the web and rendering processes start.

The build must include npm's development dependencies because Vite is a build tool. bin/rails assets:precompile builds both client assets and the SSR bundle (public/vite-ssr/ssr.js) through the app's Vite configuration. If you customize deployment, use Hatchbox's build-script documentation and keep these steps before restarting the app.

Before sending or importing subscribers:

  1. Open your HTTPS app URL and confirm the login page loads without asset or certificate errors. Inspect the ssr logs if server rendering fails.
  2. Confirm storage/production.sqlite3 is in persistent shared storage and survives a second deployment. Register its actual disk path in Hatchbox's SQLite database settings to configure database backups. Back up local uploads and imports too.
  3. Check the process list for the web process and ssr, with only the Puma-managed Solid Queue supervisor. Verify the queue workers and recurring scheduler start in the web logs.
  4. Follow Sign up on the login page to create the owner account promptly. Signup closes once the first owner exists. Your account at account.mimeohq.com is separate from this instance login.
  5. On the dashboard, follow Get set up to send, or open Settings → Provider. The sending wizard connects Resend or Postmark, creates senders and domains, collects the mailing address, and verifies domain connections.
  6. Finish Getting started: configure media storage and unsubscribe settings, connect Mimeo Manager, and send a test to an address you control. Confirm jobs actually complete, not only that the web page loads.

Avoid deploying while a CSV import is in progress. Import records refer to uploaded file paths, so preserve the release path until those imports finish as well as preserving the shared files.

Checklist for other Rails hosts