Deploy an app from Docker image

This guide explains how to deploy a single-container Docker app to Olares using Studio.

For single-container apps

This method supports apps that run from a single container image. For multi-container apps (for example, a web service plus a separate database), use the workflow in the developer documentation instead.

Recommended for testing

Studio-created deployments are best suited for development, testing, or temporary use. Upgrades and long-term data persistence can be limited compared to installing a packaged app from the Market. For production use, consider packaging and uploading the app and installing it via the Market.

Prerequisites

• Olares version 1.12.2 or later.
• A container image for the app exists and is accessible from the Olares host.
• The app's docker run command or docker-compose.yaml is available to reference configuration (ports, environment variables, volumes).

Create and configure your app

The following uses Wallos, a personal subscription and expense tracker, to show you how to map common Docker settings (image, ports, environment variables, volumes) into Studio.

Docker examples

docker run command

docker run -d \
  --name wallos \
  -v /path/to/config/wallos/db:/var/www/html/db \
  -v /path/to/config/wallos/logos:/var/www/html/images/uploads/logos \
  -e TZ=America/Toronto \
  -p 8282:80 \
  --restart unless-stopped \
  bellamy/wallos:latest

docker compose

version: '3.0'

services:
  wallos:
    container_name: wallos
    image: bellamy/wallos:latest
    ports:
      - "8282:80/tcp"
    environment:
      TZ: 'America/Toronto'
    # Volumes store your data between container upgrades
    volumes:
      - './db:/var/www/html/db'
      - './logos:/var/www/html/images/uploads/logos'
    restart: unless-stopped

Create an app

1. Open Studio and select Create a new application.

2. Enter an App name, for example: wallos, and click Confirm.

   INFO

   Use only lowercase letters and numbers.

3. Select Port your own container to Olares.

Configure image, port, and instance spec

These fields define the app's core components. You can find this information as the main image name and the -p flag in a docker run command, or under the image: and ports: keys in a docker-compose.yaml file.

1. For the Image field, paste the image name: bellamy/wallos:latest.
2. For the Port field, from a HOST:CONTAINER mapping like 8282:80, enter the Container Port only: 80.

   Container port only

   A port mapping is defined as HOST:CONTAINER. The Container Port (after the colon) is the internal port the app listens on. The Host Port (before the colon) is the external port you access. Studio manages external access automatically, so you only need to enter the Container Port.

3. For Instance Specifications, enter the minimum CPU and memory requirements. For example:
   • CPU: 2 core
   • Memory: 1 G

Add environment variables

Environment variables are used to pass configuration settings to your app. In the Docker examples, these are defined using the -e flag or in the environment: section.

1. Scroll down to Environment Variables, and click Add.
2. In this example, enter the key-value pair:
   • key: TZ
   • value: America/Toronto
3. Click Submit. Repeat this process for any other variables.

Add storage volumes

Volumes connect storage on your Olares device to a path inside the app's container, which is essential for saving data permanently. These are defined using the -v flag or in the volumes: section.

Host path options

The host path is where Olares stores the data, and the mount path is the path inside the container. Olares provides three managed host path prefixes:

• /app/data: App data directory. Data can be accessed across nodes and is not deleted when the app is uninstalled. Appears under /Data/studio in Files.
• /app/cache: App cache directory. Data is stored in the node's local disk and is deleted when the app is uninstalled. Appears under /Cache/<device-name>/studio in Files.
• /app/Home: User data directory. Mainly used for reading external user files. Data is not deleted.

Host path rules

• The host path you enter must start with /.
• Studio automatically prefixes the full path with the app name. If the app name is test and you set host path /app/data/folder1, the actual path becomes /Data/studio/test/folder1 in Files.

This app requires two volumes. You will add them one by one.

1. Add the database volume. This data is for high-frequency I/O and does not need to be saved permanently. Map it to /app/cache so it will be automatically deleted when the app is uninstalled.
   1. Click Add next to Storage Volume.
   2. For Host path, select /app/cache, then enter /db.
   3. For Mount path, enter /var/www/html/db.
   4. Click Submit.
2. Add the logo volume. This is user-uploaded data that should be persistent and reusable, even if the app is reinstalled. Map it to /app/data.
   1. Click Add next to Storage Volume.
   2. For Host path, select /app/data, then enter /logos.
   3. For Mount path, enter /var/www/html/images/uploads/logos
   4. Click Submit.

You can check Files later to verify the mounted paths.

Optional: Configure GPU or database middleware

If your app needs GPU, enable the GPU option under Instance Specifications and select the GPU vendor.

If your app needs Postgres or Redis, enable it under Instance Specifications.

When enabled, Studio provides dynamic variables. You must use these variables in the Environment Variables section for your app to connect to the database.

• Postgres variables:

Variables	Description
$(PG_USER)	PostgreSQL username
$(PG_DBNAME)	Database name
$(PG_PASS)	Postgres Password
$(PG_HOST)	Postgres service host
$(PG_PORT)	Postgres service port

• Redis variables:

Variables	Description
$(REDIS_HOST)	Redis service host
$(REDIS_PORT)	Redis service port
$(REDIS_USER)	Redis username
$(REDIS_PASS)	Redis password

Generate the app project

1. Once all your configurations are set, click Create. This generates the app's project files.
2. After creation, Studio generates the package files for your app, and then automatically deploys the app. You can check the status in the bottom bar.
3. When the app is successfully deployed, click Preview in the top-right corner to launch it.

Review the package files and test the app

Apps deployed from Studio include a -dev suffix in the title to distinguish them from Market installations.

You can click on files like OlaresManifest.yaml to review and make changes. For example, to change the app's display name and logo.

1. Click box_edit in the top-right to open the editor.

2. Click OlaresManifest.yaml to view the content.

3. Change the title field under entrance and metadata. For example, change wallos to Wallos.

4. Replace the default icon image address under entrance and metadata.

5. Click save in the top-right to save changes.

6. Click Apply to reinstall with the updated package.

   INFO

   If no changes are detected since the last deployment, clicking Apply will simply return to the app's status page without reinstalling.

   

Uninstall or delete the app

If you no longer need the app, you can remove it.

1. Click more_vert in the top-right corner.
2. You can choose to:
   • Uninstall: Removes the running app from Olares, but keeps the project in Studio so you can continue editing the package.
   • Delete: Uninstalls the app and removes the project from Studio. This action is irreversible.

Troubleshoot a deployment

Cannot install the app

If installation fails, review the error at the bottom of the page and click View to expand details.

Run into issues when the app is running

Once running, you can manage the app from its deployment details page in Studio. The interface of this page is similar to Control Hub. If details don't appear, refresh the page. You can:

• Use the Stop and Restart controls to retry. This action can often resolve runtime issues like a frozen process.
• Check events or logs to investigate runtime errors. See Export container logs for troubleshooting for details.