Skip to content

Add your own containers with custom.yml

How-toDeployrr v6.0+CurrentDocker Compose

Use custom.yml to run containers that are not in the Deployrr apps library, or to run your own version of an app. You write the Compose code. Deployrr starts it together with your other apps.

To see a custom app added by hand, watch Deployrr 5 walkthrough: Installing Custom Apps at 1:25:39 (shows Deployrr v5; menus and steps differ in v6).

To run a second copy of an app you already installed, see Run a second copy of an app. For a full example with host networking and a USB device, see Run Home Assistant as a container with custom.yml.

  • Deployrr is installed and you created your Docker folder in Prerequisites. See the Quick start.
  • You know basic Docker Compose syntax.
  • Optional: turn on the Bash aliases (Basic, Plus or Pro). This page uses cdd, dcup, dcrec and dclogs. If your Docker folder isn’t /home/YOUR_USER/docker, read Your Docker folder is somewhere else first.

All paths are inside your Docker folder. Deployrr recommends /home/YOUR_USER/docker, but you choose the folder yourself, so yours may differ. The cdd alias takes you there (see the note on other folders above).

File What it is
docker-compose-HOSTNAME.yml The main Compose file for this machine. HOSTNAME is your hostname.
compose/HOSTNAME/custom.yml Your file. It starts with only comments.

If you rename your server, see Change the hostname.

  1. Go to your Docker folder.

    Terminal window
    cdd
  2. Open the main Compose file.

    Terminal window
    nano docker-compose-$HOSTNAME.yml

    Bash fills in $HOSTNAME for you. If your editor is not nano, use the one you prefer.

  3. Find the include: section. The custom.yml line starts with #, so it is off:

    include:
    ########################### SERVICES
    # HOSTNAME defined in .env file
    # - compose/$HOSTNAME/custom.yml
    # SERVICE-PLACEHOLDER-DO-NOT-DELETE
  4. Remove the # at the start of the custom.yml line. Keep the two spaces in front of the dash.

    - compose/$HOSTNAME/custom.yml

    Leave the SERVICE-PLACEHOLDER-DO-NOT-DELETE line as it is. Deployrr uses it when you install apps.

  5. Save the file.

  6. Open your custom file.

    Terminal window
    nano compose/$HOSTNAME/custom.yml
  7. Remove the # from # services:, then add your services below it. For example:

    services:
    mycustomapp1:
    image: customimage:latest
    container_name: mycustomapp1
    restart: unless-stopped
    # Add your other options here.
    mycustomapp2:
    image: anotherimage:latest
    container_name: mycustomapp2
    restart: unless-stopped

    Replace the names and images with your own.

  8. Save the file.

  9. Start your new services. Replace SERVICE_NAME with the service name from your file, such as mycustomapp1.

    Terminal window
    dcup SERVICE_NAME

    Without the aliases, run this instead. Replace YOUR_USER and HOSTNAME with your own values.

    Terminal window
    sudo docker compose --profile all -f /home/YOUR_USER/docker/docker-compose-HOSTNAME.yml up -d SERVICE_NAME

You can also use Tools > Stack Manager > Up in Deployrr. That brings up the whole stack, not one service, and needs a Basic, Plus or Pro license. Setting up the bash aliases (for dcup) needs one of these licenses too. The plain docker compose command above works with any license.

After you edit custom.yml again, run dcup SERVICE_NAME again. Compose recreates the service if its settings changed.

To force a fresh container even when nothing changed, run:

Terminal window
dcrec SERVICE_NAME

Tools > Stack Manager > Update Stack only pulls new images for apps that Deployrr installed. It then starts the whole stack again, so your custom.yml services restart on the image they already have. Up does not pull new images either.

To update one of your services, pull its image, then start it again:

Terminal window
dcpull SERVICE_NAME
dcup SERVICE_NAME

Without the aliases, run these instead. Replace YOUR_USER and HOSTNAME with your own values.

Terminal window
sudo docker compose --profile all -f /home/YOUR_USER/docker/docker-compose-HOSTNAME.yml pull SERVICE_NAME
sudo docker compose --profile all -f /home/YOUR_USER/docker/docker-compose-HOSTNAME.yml up -d SERVICE_NAME

dcpull without a service name pulls the images of every app, your own services included. Then run dcup to start them on the new images.

If your service uses a fixed version tag, such as image: someimage:1.4.2, pulling gets nothing new. Change the tag in custom.yml first, then run the two commands above.

Tools > Stack Manager > Update App also works for a custom.yml service, as long as its container_name is the same as its service name. It needs a Basic, Plus or Pro license. For the other update options, see Update your apps.

To understand how updating a Compose service works, read UDMS part 13: Updating Services (manual setup; its folder and file names differ from Deployrr v6).

  1. Run dclogs SERVICE_NAME to read the logs of your new service. Press Ctrl+C to stop following them.

  2. List your containers.

    Terminal window
    dps

    Your service appears in the list with a status of Up.

If Compose prints an error about the file, check the indentation in custom.yml. Compose is strict about spaces.

To let your service talk to other apps, see Connect your apps to each other. To give it an HTTPS address and a login page, see Protect a custom.yml app with Traefik and a login.

What Deployrr changes and what it leaves alone

Section titled “What Deployrr changes and what it leaves alone”
  • When you install an app, Deployrr adds a line for it to docker-compose-HOSTNAME.yml, just above the SERVICE-PLACEHOLDER-DO-NOT-DELETE line. It does not edit compose/HOSTNAME/custom.yml.
  • Keep the custom.yml line and the placeholder line in the main file. Don’t rename or move them.
  • Don’t give a service in custom.yml the same name as an app Deployrr installs. Docker Compose won’t start two services with the same name.
  • If the main file loses its include: line or the placeholder line, Deployrr reports that it is malformed.

You don’t have to use custom.yml. You can add more Compose files next to it, such as mycustomapp.yml, and list them in the include: section of the main file in the same way.

Add new include lines above the SERVICE-PLACEHOLDER-DO-NOT-DELETE line:

include:
- compose/$HOSTNAME/custom.yml
- compose/$HOSTNAME/mycustomapp.yml
# SERVICE-PLACEHOLDER-DO-NOT-DELETE

To understand how the include: list works, watch Ultimate Docker Server: Creating the Docker Compose File at 14:29 (manual Docker Compose setup; folder and file names differ from Deployrr v6).