Add your own containers with custom.yml
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.
Before you start
Section titled “Before you start”- 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,dcrecanddclogs. If your Docker folder isn’t/home/YOUR_USER/docker, read Your Docker folder is somewhere else first.
Where the files are
Section titled “Where the files are”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.
-
Go to your Docker folder.
Terminal window cdd -
Open the main Compose file.
Terminal window nano docker-compose-$HOSTNAME.ymlBash fills in
$HOSTNAMEfor you. If your editor is not nano, use the one you prefer. -
Find the
include:section. Thecustom.ymlline starts with#, so it is off:include:########################### SERVICES# HOSTNAME defined in .env file# - compose/$HOSTNAME/custom.yml# SERVICE-PLACEHOLDER-DO-NOT-DELETE -
Remove the
#at the start of thecustom.ymlline. Keep the two spaces in front of the dash.- compose/$HOSTNAME/custom.ymlLeave the
SERVICE-PLACEHOLDER-DO-NOT-DELETEline as it is. Deployrr uses it when you install apps. -
Save the file.
-
Open your custom file.
Terminal window nano compose/$HOSTNAME/custom.yml -
Remove the
#from# services:, then add your services below it. For example:services:mycustomapp1:image: customimage:latestcontainer_name: mycustomapp1restart: unless-stopped# Add your other options here.mycustomapp2:image: anotherimage:latestcontainer_name: mycustomapp2restart: unless-stoppedReplace the names and images with your own.
-
Save the file.
-
Start your new services. Replace
SERVICE_NAMEwith the service name from your file, such asmycustomapp1.Terminal window dcup SERVICE_NAMEWithout the aliases, run this instead. Replace
YOUR_USERandHOSTNAMEwith 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.
Apply later changes
Section titled “Apply later changes”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:
dcrec SERVICE_NAMEUpdate your services to a newer image
Section titled “Update your services to a newer image”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:
dcpull SERVICE_NAMEdcup SERVICE_NAMEWithout the aliases, run these instead. Replace YOUR_USER and HOSTNAME with your own values.
sudo docker compose --profile all -f /home/YOUR_USER/docker/docker-compose-HOSTNAME.yml pull SERVICE_NAMEsudo docker compose --profile all -f /home/YOUR_USER/docker/docker-compose-HOSTNAME.yml up -d SERVICE_NAMEdcpull 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).
Check it worked
Section titled “Check it worked”-
Run
dclogs SERVICE_NAMEto read the logs of your new service. PressCtrl+Cto stop following them. -
List your containers.
Terminal window dpsYour 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 theSERVICE-PLACEHOLDER-DO-NOT-DELETEline. It does not editcompose/HOSTNAME/custom.yml. - Keep the
custom.ymlline and the placeholder line in the main file. Don’t rename or move them. - Don’t give a service in
custom.ymlthe 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.
Use your own file names
Section titled “Use your own file names”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-DELETETo 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).

