Project Configuration

Tell Nebion how to build and run your application by adding two files to your repository root.

.nebion.yml

Deployment config: compose file, web service, rollout tasks

docker-compose-nebion.yml

Service definitions: web server, PHP, database, etc.

Environment Variables

Injected automatically via .nebion.env (details)

Container Registries

Pull from private Docker registries

Quick Start

1. Create .nebion.yml

   This is your deployment config — it tells Nebion which compose file to use, which service handles web traffic, and what commands to run.

   docker-compose-yaml: docker-compose-nebion.yml
   nginx_service: nginx

2. Create docker-compose-nebion.yml

   Define your application services — web server, PHP, database, etc. This is a standard Docker Compose file.

   services:
     nginx:
       image: nginx:latest
     php:
       image: php:8.3-fpm
     mariadb:
       image: mariadb:10.6

3. Open a Pull Request

   Nebion clones your code, starts containers, and makes the environment accessible at pr-{number}.{domain}. Add deployment tasks to run migrations, install dependencies, and more.

Validate Your Config

Run nebioncli doctor from your project root to check .nebion.yml and your Docker Compose file for errors before deploying.

.nebion.yml Reference

Minimal

docker-compose-yaml: docker-compose-nebion.yml
nginx_service: nginx

Full Example

docker-compose-yaml: docker-compose-nebion.yml
nginx_service: nginx
traefik_port: 80

tasks:
  pre-rollout: []

  post-rollout:
    - name: Install Composer dependencies
      command: composer install -o
      service: php

    - name: Run database updates
      command: drush updb -y
      service: php

    - name: Import configuration
      command: drush cim -y
      service: php

    - name: Clear caches
      command: drush cr
      service: php

actions:
  cache-clear:
    name: "Clear Cache"
    service: php
    command: "drush cr"

  db-dump:
    name: "Database Dump"
    service: php
    command: "drush sql-dump --gzip > $NEBION_ACTION_OUTPUT/db-dump.sql.gz"
    result: file

Fields

Field	Required	Default	Description
docker-compose-yaml	Yes	docker-compose.yml	Name of your Docker Compose file
nginx_service	Yes	nginx	Service name that handles web traffic. Must match a service in your compose file.
traefik_port	No	80	Port your web server listens on inside the container
tasks	No	-	Deployment tasks to run (see Deployment Tasks)
actions	No	-	On-demand commands to run against live environments (see Actions)
traefik	No	-	Multi-service routing (see Multi-Service Routing)
container-registries	No	-	Private Docker registries (see Container Registries)

Deployment Tasks

Tasks run commands inside your containers during deployment. There are two phases:

• Pre-rollout — Runs before the new containers start, while the previous instance is still running. Use for preparation steps like enabling maintenance mode or exporting data. Only applies when redeploying an existing environment.
• Post-rollout — Runs after the new containers are up. Use for setup steps that need the new code (e.g., install dependencies, run migrations, clear caches).

Each task has three properties:

Property	Description
name	Description shown in deployment logs
command	Shell command to execute
service	Container to run it in (must match a service name in your compose file)

Tasks run in the order listed. If a task fails, the deployment stops.

Pre-Rollout Example

tasks:
  pre-rollout:
    - name: Enable maintenance mode
      command: |
        if tables=$(mysql -u $DB_USER -p$DB_PASSWORD -h $DB_HOST $DB_NAME -e "SHOW TABLES;") && [ -n "$tables" ]; then
          drush sset system.maintenance_mode TRUE
        fi
      service: php

Commands support multi-line shell scripts using the YAML | syntax.

Post-Rollout Example

tasks:
  post-rollout:
    - name: Install Composer dependencies
      command: composer install -o
      service: php

    - name: Run database updates
      command: drush updb -y
      service: php

    - name: Import configuration
      command: drush cim -y
      service: php

    - name: Clear caches
      command: drush cr
      service: php

Multi-Service Routing

By default, Nebion routes all traffic to a single service (nginx_service). If your application has multiple services that need their own URLs, use the traefik block to define routing rules.

traefik:
  services:
    web:
      service: nginx
      port: 80
    api:
      service: node-api
      port: 3000
      subdomain: api

This creates two routes for each environment:

• pr-42.example.com → nginx container on port 80
• api.pr-42.example.com → node-api container on port 3000

Service Fields

Field	Default	Description
service	Same as the key name	Docker Compose service to route to
port	80	Container port to proxy to
subdomain	-	Expose at {subdomain}.{env-domain} instead of the root domain
path_prefix	-	Match requests to {env-domain}{path_prefix} and strip the prefix before forwarding

Examples

API on a subdomain:

traefik:
  services:
    web:
      service: nginx
    api:
      service: express
      port: 4000
      subdomain: api

Routes: pr-42.example.com → nginx, api.pr-42.example.com → express:4000

Admin panel at a path prefix:

traefik:
  services:
    frontend:
      port: 3000
    admin:
      service: nginx
      path_prefix: /admin

Routes: pr-42.example.com → port 3000, pr-42.example.com/admin/* → nginx (prefix stripped)

Subdomain with a path prefix:

traefik:
  services:
    web:
      service: nginx
    docs:
      service: nginx
      subdomain: docs
      path_prefix: /v2

Routes: pr-42.example.com → nginx, docs.pr-42.example.com/v2/* → nginx (prefix stripped)

When traefik.services is defined, it replaces the nginx_service and traefik_port fields. You do not need both.

Container Registries

If your project uses private Docker images, declare the registries in .nebion.yml and store credentials as custom variables in the Nebion UI.

container-registries:
  ghcr:
    url: ghcr.io
  company-harbor:
    url: harbor.company.com

Credential Naming Convention

For each registry entry, add two custom variables using this pattern:

• Convert the registry key to UPPERCASE
• Replace hyphens with underscores
• Prepend REGISTRY_ and append _USERNAME or _PASSWORD

Registry key	Username variable	Password variable
ghcr	REGISTRY_GHCR_USERNAME	REGISTRY_GHCR_PASSWORD
company-harbor	REGISTRY_COMPANY_HARBOR_USERNAME	REGISTRY_COMPANY_HARBOR_PASSWORD
docker-hub	REGISTRY_DOCKER_HUB_USERNAME	REGISTRY_DOCKER_HUB_PASSWORD

Registry credentials are used only during deployment to pull images. They are automatically excluded from .nebion.env and are never available inside your running containers.

Supported Registries

Any Docker-compatible registry that accepts static credentials:

Registry	Username	Password
GitHub (ghcr.io)	GitHub username	Personal Access Token with read:packages scope
GitLab	Username or deploy token name	Password, PAT, or deploy token
Docker Hub	Docker Hub username	Password or access token
Harbor / self-hosted	Username or robot$name	Password or robot token
Azure ACR	Service Principal Client ID	Service Principal secret
Google Artifact Registry	_json_key	Service account key JSON

Note: AWS ECR is not supported — ECR uses short-lived tokens that require the AWS CLI to generate, which is not compatible with the static credential model.

Registry Examples

GitHub Container Registry:

container-registries:
  ghcr:
    url: ghcr.io

Custom variables:

REGISTRY_GHCR_USERNAME = <github-username>
REGISTRY_GHCR_PASSWORD = ghp_xxxxxxxxxxxx

services:
  php:
    image: ghcr.io/myorg/php-app:latest

The PAT requires the read:packages scope.

Docker Hub (private repository):

container-registries:
  docker-hub:
    url: https://index.docker.io/v1/

Custom variables:

REGISTRY_DOCKER_HUB_USERNAME = <dockerhub-username>
REGISTRY_DOCKER_HUB_PASSWORD = dckr_pat_xxxxxxxxxxxx

Docker Hub images have no registry prefix - Docker resolves unqualified images to docker.io automatically.

Self-hosted Registry (Harbor):

container-registries:
  wsagency:
    url: registry.wsagency.io

Custom variables:

REGISTRY_WSAGENCY_USERNAME = <username>
REGISTRY_WSAGENCY_PASSWORD = <token>

Multiple Registries:

container-registries:
  wsagency:
    url: registry.wsagency.io
  ghcr:
    url: ghcr.io

Add credentials for each:

REGISTRY_WSAGENCY_USERNAME = <username>
REGISTRY_WSAGENCY_PASSWORD = <token>
REGISTRY_GHCR_USERNAME = <github-username>
REGISTRY_GHCR_PASSWORD = ghp_xxxxxxxxxxxx

Nebion authenticates to each registry independently before starting containers.

Generated Files

Nebion creates and manages these files during deployment — you don't need to create them.

.nebion.env

Nebion generates .nebion.env during each deployment. It contains:

1. System variables (NEBION_DOMAIN, NEBION_PR_NUMBER, etc.)
2. Your custom variables from the Nebion UI

All variables are automatically available in every container. See Environment Variables for details.

If your repository has a .env file, it is loaded first. Variables in .nebion.env override those in .env. If .nebion.env already exists in your repository, Nebion extends it with additional variables.

docker-compose-pr.yml

Nebion generates docker-compose-pr.yml from your docker-compose-nebion.yml during deployment. It adds:

• Container naming with project and PR identifiers
• Network configuration for routing
• Environment file injection (.env and .nebion.env)

You do not need to create or edit this file.