Custom Prebuilt

While Zeabur already includes numerous Prebuilt Images and templates provided by the community, you might need to deploy your own Docker images, configure persistent storage, set start command, and more. For this need, Zeabur offers customizable Prebuilt functionality.

Open Interface

Click "Add Service" → "Prebuilt Images" → "Customize" to open the Prebuilt customization page.

Configuration Instructions

Image

"Image" is the Docker image to be pulled, typically the image tag following docker pull or docker run, such as

docker pull mariadb      # tag is "mariadb"
docker run mariadb:lts   # tag is "mariadb:lts"

Or in Docker Compose

version: '3.9'
services:
  db:
    image: postgres      # tag is "postgres"
    # ...

After setting up, you can proceed to configure environment variables, ports, etc.

Environment Variable

"Environment Variable," as the name implies, is the environment variable passed to the service. In addition to basic environment variable settings, Zeabur also allows you to expose these variables to other services and set them as "readonly" (immutable).

"Key" is the environment variable key, allowing only letters, numbers, and underscores, such as MARIADB_USER or DB_1_HOST.

"Value" is the environment variable value, which can include ${KEY} references to other variables. As shown above, MARIADB_PASSWORD references MARIADB_ROOT_PASSWORD, so its value equals 123456. Likewise, if a variable value is password=${MARIADB_PASSWORD}, it expands to password=123456. This ${KEY} format expands at service startup, so the application sees the expanded value.

"Expose" makes the variable available to other services. For instance, MARIADB_USERNAME and MARIADB_PASSWORD are exposed, making them accessible to other services in the same project.

"Readonly" means the variable cannot be modified after Prebuilt creation. For example, MARIADB_PASSWORD marked as readonly, so members cannot change its value. Note that its value still reflects to the current MARIADB_ROOT_PASSWORD value.

Aside from variables Exposed by other services, you can also use Zeabur's predefined special variables, such as using ${ZEABUR_WEB_URL} to retrieve the URL set on the web port.

If you are write a Prebuilt according to a Docker image documentation, environment variables often follow docker run with --env (or -e), such as:

docker run --detach --name some-mariadb --env MARIADB_USER=example-user --env MARIADB_PASSWORD=my_cool_secret --env MARIADB_DATABASE=example-database --env MARIADB_ROOT_PASSWORD=my-secret-pw  mariadb:latest
 
# MARIADB_USER          = example-user
# MARIADB_PASSWORD      = my_cool_secret
# MARIADB_DATABASE      = example-database
# MARIADB_ROOT_PASSWORD = my-secret-pw

In Docker Compose:

version: '3.9'
services:
  adminer:
    image: adminer
    restart: always
    environment:
      DEBUG: "true"   # (or) - DEBUG=true
      # DEBUG = true

Ports

"Ports" function like firewall inbound rules, allowing only declared ports to be accessed by other services or the external network.

"Port Name" should consist only of letters and dashes. "Port" is the service listening port, such as 3306 for MariaDB or 8080, 3000, 80 for web services.

"Port Type" can be HTTP or TCP. For external access, HTTP ports can be accessed with a domain (e.g., my-service.zeabur.app) that contains the automatic TLS certificate signing by Zeabur, while TCP ports can be accessed with an auto-assigned hostname and port (e.g., reg.clusters.zeabur.com:12345). For inter-service connections, you can access the port with Private Networking, which reduces unnecessary traffic costs. To access this port in other services, use the declared port directly (mariadb.zeabur.internal:3306, backend.zeabur.internal:8080).

If you are write a Prebuilt according to a Docker image documentation, ports follow docker run with -p, such as:

docker run -p 3306 mariadb:latest
 
# Port Name = <Custom>; Port = 3306; Port Type = TCP
# TCP because MariaDB uses a custom TCP-based protocol.

In Docker Compose:

version: '3.9'
services:
  adminer:
    image: adminer
    restart: always
    ports:
      - 80:8080
      # Port Name = <Custom>; Port = 8080; Port Type = HTTP
      # HTTP because adminer is a PHP web interface for database management.

Volumes

"Volumes" are paths for persistent storage.

By default, Zeabur resets the service data to the image's default state upon each restart (stateless). To store data long-term in a container, you can configure persistent storage and mount it to the desired directory. This ensures that the mounted directory remains unchanged on restarts or updates, until you delete the service or modify the directory contents. The "Backup" feature also backs up this space. Refer to Zeabur Pricing (opens in a new tab) for persistent storage charges.

"Volume id" is the storage space identifier, consisting only of letters, numbers, and dashes. "Path" is the mount path, configured according to the Docker image's Volume settings.

In Docker image documentation, volumes follow docker run with -v, such as:

docker run -v your-storage:/var/lib/mysql mariadb:latest
 
# Volume ID = <Custom>; Path = /var/lib/mysql

In Docker Compose:

version: '3.9'
services:
  mariadb:
    image: mariadb
    volumes:
      - your-storage:/var/lib/mysql
      # Volume ID = <Custom>; Path = /var/lib/mysql

Start Command

"Start Command" allows you to override the default Docker image entrypoint and arguments. This is an advanced setting and can be skipped if you are unsure what it is.

When specifying from the GUI, the default entrypoint when setting this field is /bin/sh. If your image does not provide /bin/sh, use Edit TOML to change it or consult support for assistant.

Manually Write Prebuilt TOML

Although the GUI offers many necessary parameters for creating Prebuilt services, you might want to add custom icons, connection instructions, or detailed settings. In this case, use Edit TOML for a more comprehensive (and complex) Prebuilt TOML file.

Refer to the Prebuilt TOML JSON schema (opens in a new tab) for each field explanation, and the TOML documentation (opens in a new tab) for writing instructions. If you have any questions, feel free to contact support.