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.

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

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]. The list form currently supports one port. See Endpoints.
authEndpoint auth mode. Supported values are none, login, and token. See Auth.
perMachineEndpointsOptional. Set perMachineEndpoints: true to create direct per-machine endpoint URLs instead of one shared load-balanced endpoint. Required for multi-machine public services on plans without load balancing.
preferLanOptional. Set preferLan: true on a public service to also bind the service on the machine's LAN address. Nethera will try to detect if you are on the same local network and redirect you to the local address when possible. Useful for saving bandwidth. See Local access.
onServiceFailurePro only. Sends email alerts and invokes customer-managed webhooks when every backend for the public service remains unreachable for the configured duration.
onServiceFailure.afterDuration all backends must remain unreachable before alerts are triggered. Defaults to 60s. Minimum 10s, maximum 1h.
onServiceFailure.emailsEmail recipient groups. Supported values are owners and admins.
onServiceFailure.webhookSecretsNethera secret names containing webhook URLs. Webhooks can notify Slack, incident tools, or failover automation.
secretsApp-scoped secrets injected as environment variables at deploy time. Set with neth secrets set.
imagePullCredentialsPro only. App-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.
postDeployUp to 10 shell commands, each up to 1000 characters, run inside the service container after docker compose up -d. They run on every deploy and should be safe to repeat. Nethera waits until container exec is available, but app-specific readiness should be handled by your command or a Compose healthcheck.

Post-deploy commands

Use postDeploy for small, repeatable setup steps that should run inside the service container after Compose has started it. This is useful for one-time model pulls or app setup commands, but the command should be written so it can safely run again on the next deploy.

nethera.yml
services:
  ollama:
    image: ollama/ollama:latest
    nethera:
      postDeploy:
        - |
          until ollama list >/dev/null 2>&1; do
            sleep 2
          done
          ollama pull llama3.2

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 can import the Compose file, but it does not rewrite every unsupported local feature for you.

network_mode: host is supported for image-based services. If a host-network service is public, Nethera exposes the selected container/host port through the endpoint. Be careful with port conflicts, because host networking uses the machine's own network namespace.

Core conceptsEndpoints