Skip to content
BeamUpbeamup docs

Deploying Existing Gleam Apps

BeamUp SLC v1 supports Erlang-targeted Gleam HTTP apps that can be exported as an Erlang shipment and started without a BeamUp SDK.

App Requirements

Section titled “App Requirements”

Your app must:

  • Have a gleam.toml at the project root or under the configured app_root.
  • Target Erlang. An omitted target in gleam.toml is treated as Erlang.
  • Build with gleam export erlang-shipment.
  • Start with an argv command, usually ["./build/erlang-shipment/entrypoint.sh", "run"].
  • Read PORT from the environment at process startup.
  • Bind HTTP traffic on 0.0.0.0:<PORT>.
  • Return HTTP 2xx from the configured health path.
  • Avoid exposing secrets, request headers, env values, or runtime internals from the health path.

The canonical test fixture uses Wisp and Mist, but BeamUp is not limited to Wisp/Mist. It is a platform for supported Erlang-targeted Gleam HTTP apps.

Initialize

Section titled “Initialize”

From the project root:

Terminal window
beamup init

If beamup.toml does not exist, BeamUp writes defaults based on gleam.toml. If the file exists, BeamUp validates it and makes no changes.

To replace an existing valid config with schema defaults:

Terminal window
beamup init --overwrite

--config <PATH> is accepted for init only when the path resolves to beamup.toml in the detected project root.

Local Build Check

Section titled “Local Build Check”

Run your normal tests, then verify the export path:

Terminal window
gleam test
gleam export erlang-shipment

Run the app with a local port:

Terminal window
PORT=8000 ./build/erlang-shipment/entrypoint.sh run

Then verify health:

Terminal window
curl -i http://127.0.0.1:8000/healthz

Deploy

Section titled “Deploy”
Terminal window
beamup deploy

beamup deploy packages the project as a deterministic tar.gz, uploads it, creates an immutable deployment, and starts the build/runtime path. Plain output includes:

  • Deployment ID.
  • App slug and name.
  • Compressed archive size and included file count.
  • Initial deployment state.
  • A build-log command for the deployment.

The active deployment pointer moves only after the candidate runtime starts and passes the configured health check. A failed build, startup failure, port failure, or health-check failure does not replace the current healthy active deployment.

Status

Section titled “Status”

From a project with beamup.toml:

Terminal window
beamup status

Or by app slug or ID:

Terminal window
beamup --app hello-gleam status

Status shows the app URL, active deployment, latest deployment, latest failure summary when present, drain/shutdown metadata, and compact runtime snapshot availability.

App URL

Section titled “App URL”

The default URL is:

https://<app>.beamup.run

The app URL stays stable across redeploys and rollback. Custom domains are not supported in SLC v1.

Package Limits

Section titled “Package Limits”

Packaging fails before upload when:

  • Uncompressed source exceeds 50 MiB.
  • The compressed archive exceeds 50 MiB.
  • More than 5,000 files would be included.

Use normal ignore files to keep build output, local caches, and private files out of the source package.

Common Failures

Section titled “Common Failures”
  • missing_gleam_toml: run from the project root or fix app_root.
  • unsupported_target: use an Erlang-targeted Gleam project.
  • invalid_config: fix the named beamup.toml field.
  • compile_failure: inspect build logs and rerun the Gleam build locally.
  • port_binding_failure: read PORT and bind on 0.0.0.0:<PORT>.
  • startup_failure: inspect runtime logs and fix the start command or app startup path.
  • health_check_failure: make the configured health path return HTTP 2xx.