Self-hosted services from public Docker images

​

Verified examples

• Meilisearch

​

Before you begin

1. Install the Upsun CLI.
2. Run the following commands to log in and connect the current Git repository to the correct Upsun project. Replace <PROJECT_ID> with your project ID (run upsun projects to list them).
   upsun login
   upsun auth:info
   upsun set-remote <PROJECT_ID>
   upsun project:info
   upsun environment:info
   

​

Configure an app

• Set type to docker:1.
• Set image.name to the image tag to run. Images without a registry hostname are pulled from Docker Hub. For images from other registries, include the full registry hostname in image.name.

# Minimal configuration. Add a custom start command, mounts, or
# environment variables to this app definition as needed.
applications:
  myapp:
    type: docker:1
    image:
      name: "<registry-or-namespace>/<image>:<tag>"

    web:
      upstream:
        socket_family: tcp
      locations:
        "/":
          passthru: true

routes:
  "https://myapp.{default}/":
    type: upstream
    upstream: "myapp:http"

​

Deploy an app

git add .upsun/config.yaml
git commit -m "Add Docker image app"
upsun push

upsun route:list

​

Startup commands

• $PORT changes to a platform-assigned value. Make sure the command indicates to listen on $PORT; otherwise, the app may listen on the wrong port and return 502 Bad Gateway errors.
• Environment variables in web.commands.start are passed literally unless the command runs through a shell. If the image includes sh, use sh -c "..." when you need environment variable expansion.

applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    web:
      commands:
        start: 'sh -c "./myapp --listen=:$PORT --db-host=$DATABASE_HOST"'

​

Mounts

applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    mounts:
      "/data":
        source: storage
        source_path: data

​

Environment variables

applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    variables:
      env:
        APP_ENV: "production"

​

Updating the image version

• For fixed version tags, commit the tag change and run upsun push.
• For latest tags, trigger a redeploy so Upsun pulls the current image for that tag.

​

Debug an app over SSH

upsun ssh --app myapp

• View logs, such as /var/log/app.log, to debug start command failures.
• Inspect the environment around the image’s container, for example mounts, networking, and process state, without needing a shell inside the image. The process list shows whether the app’s start command is running, still starting, or crash-looping, which is the main signal available when the health check fails and the image has no shell to exec into:
  pwd
  env
  ps -ef
  ls -la /
  
• Enter the image’s own container, if it includes a shell. Upsun cannot inject a shell into an image it does not control.

​

Limitations

• Docker image apps use pre-built images. Upsun does not build a Dockerfile from the repository for this app type.
• Build hooks are not supported for Docker image apps.
• Meilisearch is the only image currently verified to work on Upsun. Other public images may work but have not been tested.
• You are responsible for updating images when image publishers release security fixes.
• Docker images include their own filesystem and can use more project storage than Upsun’s built-in runtime images.
• Keep images under 4 GB. Larger images require different storage handling. To use an image larger than 4 GB, create a Support ticket and provide the full image name and registry path. To keep image size down:
  • Use a minimal base image such as alpine, distroless, or busybox.
  • Avoid bundling build tools or caches into your production image.
  • Use multi-stage builds to separate build and runtime layers.
  Minimal images such as distroless and busybox may not include shell tools such as sh, base64, or jq. This affects startup command expansion and any logic that depends on decoding PLATFORM_RELATIONSHIPS.