Documentation

Getting started#

Create an account at app.maxlayer.cloud. Signing up creates your first organization — the container for your apps, your team, and your billing. You can create more later, and belong to as many as you like.

From there, New app asks four things: where your code lives, which plan it runs on, how it should be built, and what port it listens on. Most projects answer the first two and leave the rest alone.

Connecting a git host#

Settings → Integrations. Connect a host once, then deploy any repository it can reach. Connecting or disconnecting needs the admin or owner role. GitHub and GitLab are the adapters that exist today — GitLab on gitlab.com only, not self-managed instances. The interface carries Bitbucket, but its adapter does not.

What the access is used for#

Authorising a host lets Maxlayer do three things, and no others:

• Read the list of repositories you can reach, and their branches.
• Add a read-only deploy key to a repository when you deploy it. The key works for that one repository and cannot push.
• Add a push webhook, so new commits build automatically.

Disconnecting#

Disconnecting makes Maxlayer forget the authorization. It does not reach back into repositories that are still in use and remove their deploy keys and webhooks — delete those apps first if you want them cleaned up.

A host shown as unavailable has no OAuth application registered on this Maxlayer deployment. You can still deploy from a container image while that is the case.

Deploying#

Two kinds of source. Pick whichever your project already is.

From a repository#

Authorise the repository and pick a branch. Every push to that branch triggers a build. If your project is not at the repository root, set the build path.

From a container image#

Name an image and, for a private registry, credentials. There is no build step — we pull and run it.

Build types#

The default is automatic detection, which inspects your project and works out how to build it. If a Dockerfile is present and you would rather use it, choosedockerfile. static serves built output directly.

How builds work covers what gets detected, how to steer a build with a configuration file, a Procfile, or build variables — and what to do when one fails.

Redeploying#

Redeploy rebuilds from the current source. Stop takes the app offline without deleting anything, and Start brings it back. All three are available in the dashboard and over the API.

Changing an app later#

Everything chosen at creation is editable under the app's Settings tab: its name and description, the build type, and the port it listens on. Leave the build type alone unless a build has failed — automatic detection reads your project and works it out.

Change plan moves the app to different CPU and memory. The new limits are applied when the container is next recreated, so they take effect on the following deploy rather than immediately; the dashboard says so when you save.

Where the source is a repository, the same tab shows which repository and branch it builds from and the fingerprint of the deploy key installed on it — so you can match it against the read-only key listed in your own repository settings. The deploy on every push switch saves the moment you flip it rather than waiting for a Save button, because it changes what happens on your next push.

Deleting an app#

Deleting removes the app from Maxlayer and destroys the running container. Domains, variables and deploy history go with it, and it cannot be undone — you type the app's name to confirm. Deleting needs the admin role.

Deployments and logs#

The Deployments tab is the history of every build, newest first, with its status, when it ran and how long it took. A deploy that came from a push also carries the short commit SHA, the commit message, and who pushed it.

Selecting a deployment shows its log beside the list. The newest one is followed automatically until you pick a different one, at which point the page stops moving under you.

Following output#

Follow output keeps the log pinned to the newest line while a build runs, and the viewer marks itself Streaming… until the build finishes. Scrolling up switches following off so you can read; scrolling back to the bottom switches it on again. A running deployment can be cancelled from its header if you hold the developer role or higher.

Runtime and health#

An app's Overview tab reports what its container is doing right now: the state it is in — running, restarting, exited, dead and the rest — how long it has been up, how many times it has restarted, and the container and image it is running from.

Where your application defines a health check, the result sits beside the state: passing, failing, or still starting. Where it defines none, nothing is claimed either way. There is a Restart control for the developer role and above.

Why it stopped#

When a container is not running, the panel explains why in plain language rather than handing you an exit code to go and look up — a container killed for exceeding its memory limit says exactly that. A container that has restarted three or more times without staying up is called out as restarting repeatedly, because that is the most important fact on the page when it is true, and the deployment log usually says why.

If the machine running your app cannot be reached at all, the panel says that too. Your app may well still be up — what is missing in that case is our view of it, not necessarily the app.

CPU and memory#

Environment variables#

Set variables under the Environment tab. You can add them one at a time, or paste an entire .env file and have it parsed for you.

Mark a variable as a secret and it becomes write-only: your application receives it, but it is never returned to the dashboard or the API again. Replace a secret whenever you like; you cannot read one back. Editing other variables leaves your secrets untouched.

A stored secret shows as unchanged rather than as a value. Leave it that way and it stays as it is; type into it to replace it.

Changes apply on the next deploy. Tick redeploy after saving to trigger one immediately.

Bulk import#

Paste an entire .env file into Bulk import and it is merged into the list by key — a key already present is overwritten, and everything else is left alone. Nothing is saved until you save, so you can review the merge first. A line that cannot be parsed is reported by line number instead of being silently dropped, and two rows with the same key are rejected on save rather than one quietly winning.

Imported variables arrive as ordinary values. Mark the sensitive ones secret yourself.

Databases#

Databases → New database. Choose an engine — PostgreSQL, MySQL, MariaDB, MongoDB or Redis — give it a name, and pick a plan. Database plans are separate from application plans and carry more memory at a similar price.

The database runs inside your own project, on the same network as your applications, and starts with no public address at all — your apps can reach it, and nothing else on the internet can.

To connect a local client, open Access and publish it on a port. That takes an explicit confirmation, and you can close it again at any time — closing needs no confirmation.

The same panel rotates the password. Rotating restarts the database and breaks anything still holding the old connection string — the dashboard names the applications that will need re-attaching.

Logs#

Logs shows the database's own output, with a time window, a line count and a search term. Filtering happens on the server, so a busy database does not have to send its whole history to be searched.

Attach writes the connection string into an application's environment as a secret, and offers to redeploy so it takes effect. The suggested variable name follows the engine — REDIS_URL for Redis, DATABASE_URL otherwise — and you can change it.

Stopping a database stops billing for it and keeps its data. Deleting one destroys the data — dumps already written to your bucket survive, but anything since the last backup does not.

Backups#

Backups go into an S3-compatible bucket you own — Amazon S3, Cloudflare R2, Backblaze, MinIO — so your recovery copy stays in your own account. Connect one underSettings → Backups; we test the connection before saving it, so a typo fails there rather than silently producing nothing.

Each database then gets its own schedule: every six hours, daily, or weekly, with a retention count. The exact minute is spread across the fleet so every backup does not start at the same instant.

Custom domains#

Attaching a domain takes two steps.

1. Point a CNAME record at the target shown in your app's Domains tab. For an apex domain, use an A record instead.
2. Add the hostname in the dashboard.

Once DNS resolves, a Let's Encrypt certificate is requested and installed automatically, and renewed before it expires. Propagation is usually quick but can take up to an hour.

Attach as many hostnames to one app as you like. Each carries a path, left at / to serve the whole site, and the port your process listens on — so two hostnames can route to different ports of the same app.

An app with no custom domain is not unreachable: it is already served on its Maxlayer address, and attaching your own hostname is what puts it on a name you own.

Your team#

Invite people under Team. Every member holds one of four roles:

Invitations are sent by email with the role already attached and expire after seven days. Pending ones are listed under the members, so you can see who has been asked and has not yet accepted. A member's role can be changed from the members list at any time.

Billing and credit#

Settings → Billing. Everything you run draws from a prepaid balance, hour by hour. The page opens on three figures: your balance, the rate everything currently running adds up to — per hour, with the monthly equivalent beside it — and your runway, which is how long the balance lasts at that rate. Under three days of runway is called out as a warning.

Adding credit#

Add credit takes a preset — $10, $25, $50 or $100 — or any amount from $5 upward, tells you roughly how many days it buys at your current rate, and hands you to PayPal to approve it. Top-ups are one-off: there is no subscription and no stored card. Paying needs the admin or owner role.

A payment that does not complete is listed with its status and the reason it failed, rather than disappearing. If payments are not configured on your Maxlayer deployment, the page says so and an administrator adjusts balances directly.

What you were charged for#

Usage lists hourly charges grouped by day and by app, so a bill traces back to the thing that caused it — including apps you have since deleted. The first charge appears about an hour after an app starts running. Payments and adjustments is everything else that moved your balance: top-ups, refunds, and any manual adjustment.

API and keys#

Everything the dashboard does, it does over a REST API athttps://api.maxlayer.cloud/v1 — and so can you. Create a key underAPI keys, choosing the role it carries. Give CI the least it needs.

A key takes a name so you can recognise it later, and an optional expiry in days. Leave the expiry blank and it never expires — an expiry you have to renew is safer than one you forget. Managing keys needs the admin or owner role.

Deploy an app#

curl -X POST https://api.maxlayer.cloud/v1/orgs/$ORG/apps/$APP/deploy \
  -H "Authorization: Bearer $MAXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Release v2.4.0"}'

Errors#

Every failure comes back in the same envelope. The requestId is worth quoting if you contact support — it is how we find your request in the logs.

{
  "error": {
    "code": "conflict",
    "message": "That hostname is already attached to an app",
    "requestId": "3f9c1a2e"
  }
}