nethera
Dashboard

Core concepts

nethera.yml

The Compose-style app spec used by Nethera deployments.

nethera.yml is a Docker Compose file with two additions: a few top-level fields that identify the app and where it deploys, and a nethera: block on any service you want Nethera to manage, a public endpoint, secrets, or config files. Standard service fields are used to generate Docker Compose on the target machine; everything else is handled by Nethera.

Important

nethera.yml deploys container images, not local source. You can't paste in a docker-compose.yml that builds from a local Dockerfile and expect it to work unchanged, see notes on compatibility below. Builds will be supported in future releases.

You can create a nethera.yml file from existing docker-compose.yml by running neth init.

Example

nethera.yml
appName: nethera
appId: 0yq6
targets:
  - test-machine         # <--- app is deployed here
 
services:
  web:
    image: ghcr.io/acme/example-app:latest
    environment:
      NODE_ENV: production
    volumes:
      - /mnt/nethera/example-app:/data
    nethera:
      public: 3000       # <--- connects port 3000 to a public https url
      auth: login        # <--- only logged in nethera users can access
      secrets:
        - API_KEY        # <--- injects API_KEY into container as env var
      files:
        app.conf:        # <--- text file is copied from dev workspace to machine
          source: ./app.conf
          target: /etc/example-app/conf.d/default.conf

Top-level fields

FieldDescription
appNameApp name. Used in the CLI and dashboard to identify this app.
appIdUnique app identifier, generated by neth init. Don't edit by hand.
targetsPaired machine names this app deploys to. Can list more than one.

The nethera: block

FieldDescription
publicContainer port to expose through a public endpoint, for example public: 8188 or public: [8188]. This port does not need to be listed under Compose ports. Nethera also injects endpoint env vars such as NETHERA_PUBLIC_URL, NETHERA_PUBLIC_HOST, and NETHERA_WEB_URL. See Endpoints.
authEndpoint auth mode. Supported values are none, login, and token. See Auth.
secretsApp-scoped secrets injected as environment variables at deploy time. Set with neth secrets set.
imagePullCredentialsApp-scoped secrets used by the agent to pull private images. See Private images.
filesSmall local text files, config files, for example, read by the CLI at deploy time and mounted into the service. See Managed files.

A note on Compose compatibility

nethera.yml deploys container images you've already built and pushed, it doesn't build from a local Dockerfile or upload a project directory.

If you're importing an existing docker-compose.yml, the main things to adjust are swapping build: for image:, and using absolute host-machine paths for volumes (/mnt/nethera/app-data:/data) rather than relative local paths (./data:/data). neth init handles this conversion for you when importing an existing Compose file.

Core conceptsEndpoints