Setup
elements man deploy/setupReference for a machine that already exists. With no machine yet, use AWS (opens in a new tab) instead: it does all of this for the user.
What the deploy machine needs, where the database runs, and the config that describes both.
Prerequisites
- An Ubuntu box with SSH access, on the latest Ubuntu release your provider offers. A new machine is the usual starting point. AWS (opens in a new tab) is the provider Elements recommends and DigitalOcean (opens in a new tab) works the same way with fewer services; both pages walk an agent through making one, and any provider that gives you Ubuntu over SSH works too.
- A domain name pointed at the machine's public IP, or an elements.online
name from
elements domain(see Domain (opens in a new tab)). Optional: without one the app is reachable athttp://<public-ip>over plain HTTP.
You give Elements the public and private IPs of the machine and SSH credentials. Elements takes care of the rest, including provisioning, the system user, systemd, the load balancer, automatic SSL, and the deploy itself.
Where the Database Runs
Two tiers, chosen at the first deploy and changed later with a recipe. See Sizing (opens in a new tab) for choosing.
Prototype: the bundled Postgres on the deploy machine. Nothing to
provision. On first deploy Elements installs and starts the same Postgres
cluster development uses, managed by the per-machine elements-machine
daemon, with its data under /elements/db. The scaffolded config.jsoc sets
host: env("DB_HOST", "127.0.0.1") and the scaffolded production.env sets
DB_HOST=127.0.0.1, so a deploy talks to that cluster with no further
configuration. It is not backed up, and a second machine needs the move in
Operations (opens in a new tab).
Production: a managed Postgres at the provider. The database starts on
the provider's managed Postgres (AWS RDS, DigitalOcean Managed Databases, or
any hosted Postgres 16 or newer) from the first deploy. Backups, restore, and
a second app machine are then a deploy away. Point the DB_* values in the
environment's env file at it:
config/env/production.envDB_HOST=mydb.abc123.us-east-1.rds.amazonaws.com DB_PORT=5432 DB_USER=elements DB_PASSWORD=... DB_SSL_ROOT_CERT=config/certs/db-ca.pem
The connection is encrypted with TLS. DB_SSL_ROOT_CERT names the
provider's CA certificate, committed to the project, and every machine then
verifies the server against it (verify-full, what HIPAA deployments use).
See elements man database. Elements creates the app and test databases on
the server at the first build.
On production, migrations are forward-only.
Several Machines
To run several machines, point every machine's DB_HOST at one shared
Postgres. Every feature then works across all of them with no other change:
live tables, channels, sessions, jobs, and cron. A write on any app server
reaches watching browsers on every app server, because broadcasts travel
through the shared database, and each cron tick runs on one machine.
Uploaded files go in Postgres, where every machine reads them, or in S3 or
any object store. See elements man recipes/file-upload.
The Config
config.jsoc{ deploy: { domain: "example.com", // or ["example.com", "www.example.com"] ssl: true, // default true when domain is set ssh: { user: "ubuntu", identityFile: "~/.ssh/id_ed25519", }, env: { production: { machines: [ { name: "production0", publicIp: "203.0.113.10", privateIp: "10.0.0.10" }, ], }, staging: { domain: "staging.example.com", machines: [ { name: "staging0", publicIp: "203.0.113.20", privateIp: "10.0.0.20" }, ], }, }, }, }
domain takes one host or a list of them, and every host in it goes into the
TLS certificate.
Machine names are zero-indexed: the first machine in an environment is
production0, the second production1, and so on. publicIp is where Elements
connects, and is required. privateIp is for machine-to-machine traffic in a
multi-box cluster; leave it out for a single machine or if you don't have it.
Run:
Terminalelements deploy # default: production elements deploy staging # named environment