Configuring Docker Networks in Unraid

Docker is running on your Unraid server, but your containers are living in isolation and cannot talk to each other. This tutorial walks you through how Docker networking works, how to create a shared custom network, and how to connect your containers to it so they can communicate privately without exposing extra ports.

Executive Summary

#

By default, Docker containers on Unraid use a built-in bridge network that does not allow containers to find each other by name. This tutorial covers how to create a custom Docker network called core_net that your containers can share. Any container connected to core_net can reach any other container on that network using the container name as a hostname. This is how services like a database and a web application can communicate internally without either one needing to be exposed to the internet.

Prerequisites

#

Implementation

#

Step 1: Understand how Docker networking works

#

Before creating anything, it helps to understand what a Docker network actually is.

When you install Docker on Unraid, it creates a default network called bridge. Every container you launch gets attached to this network automatically unless you tell it otherwise. The problem is that containers on the default bridge network cannot reach each other by name. They can only communicate using internal IP addresses, which change every time a container restarts.

Docker supports several network types, but in a home server environment you will mostly work with two:

The goal of this tutorial is to create a custom bridge network (core_net) that your containers can join so they can communicate by name.

Step 2: Open the Unraid terminal

#

You will use the Unraid terminal to run Docker commands. There are two ways to get there.

Option A: Unraid web UI terminal

1. In the Unraid web UI, click the terminal icon in the top-right corner of any page (it looks like >_).
2. A terminal window opens in your browser.

Option B: SSH If you have SSH enabled on Unraid (covered in Setting Up SSH and SSL in Unraid), open a terminal on your computer and connect:

ssh root@YOUR_UNRAID_IP

Replace YOUR_UNRAID_IP with the local IP address of your Unraid server (for example, 192.168.1.10).

Either method gives you a root shell on the Unraid server, which is what you need.

Step 3: Check what Docker networks already exist

#

Before creating anything, see what is already there. Run:

docker network ls

You will see output similar to this:

NETWORK ID     NAME      DRIVER    SCOPE
a1b2c3d4e5f6   bridge    bridge    local
b2c3d4e5f6a1   host      host      local
c3d4e5f6a1b2   none      null      local

These three networks are created automatically by Docker and are always present. The bridge network is the default. The host network gives containers direct access to the host machine’s network. The none network disables networking entirely.

Your output may look slightly different. Unraid often adds a fourth network called br0 with a driver of macvlan. This is Unraid’s own bridge interface that allows containers to appear as separate devices on your LAN with their own IP addresses. You do not need to touch it for this tutorial.

Notice that there is no core_net yet. You will create it in the next step.

Step 4: Create the core_net custom network

#

Run this command to create a new custom bridge network named core_net:

docker network create core_net

Docker will respond with a long string of letters and numbers. That is the unique ID of your new network. It is normal and means the network was created successfully.

Confirm it exists:

docker network ls

You should now see core_net in the list:

NETWORK ID     NAME       DRIVER     SCOPE
a1b2c3d4e5f6   br0        macvlan    local
b2c3d4e5f6a1   bridge     bridge     local
c3d4e5f6a1b2   core_net   bridge     local
d4e5f6a1b2c3   host       host       local
e5f6a1b2c3d4   none       null       local

Your custom network is ready.

Step 5: Inspect the network

#

You can see detailed information about core_net at any time:

docker network inspect core_net

The output is a block of JSON (JavaScript Object Notation, a structured text format). The important parts are the Subnet and Gateway fields under IPAM.Config. These are the internal IP address ranges Docker assigned to this network. You do not need to change these, but it is useful to know they are there.

The Containers section will be empty for now. Once you connect containers to core_net, they will appear here with their assigned internal IP addresses.

Step 6: Connect an existing container to core_net

#

If you have containers already running, you can connect them to core_net without restarting them.

To connect a running container to core_net:

docker network connect core_net CONTAINER_NAME

Replace CONTAINER_NAME with the actual name of your container. To find a container’s name, run:

docker ps

This lists all running containers. The NAMES column on the far right is what you want.

For example, to connect a container named mariadb:

docker network connect core_net mariadb

The container is now on both its original network and core_net. You do not need to stop or restart it.

Step 7: Configure new containers to use core_net

#

For containers you deploy going forward, you can specify core_net in their network settings so they join the network from the start.

If you use Docker Compose (recommended), add the network to your compose file:

services:
  my-service:
    image: some-image:latest
    container_name: my-service
    networks:
      - core_net

networks:
  core_net:
    external: true

The external: true line tells Docker Compose that core_net already exists and should not be created fresh. Without it, Compose would try to create a new network and fail because the name is taken.

If you launch containers from the Unraid UI (Docker tab), look for a “Network Type” dropdown when editing a container template. Select Custom: core_net from the list.

Step 8: Verify container-to-container communication

#

Once two containers are on core_net, they can reach each other using their container names as hostnames.

To test this, open a shell inside one container:

docker exec -it CONTAINER_NAME sh

Replace CONTAINER_NAME with the name of a container that is on core_net. Once inside, try to ping another container on the same network by name:

ping other-container-name

If the ping returns responses, the containers can see each other. Type Ctrl+C to stop the ping, then exit to leave the container shell.

Note: Some minimal container images do not include ping. If the command is not found, you can also test connectivity using wget or curl if those tools are available, or simply proceed knowing the network configuration is correct.

Step 9: Make core_net persist across Unraid reboots

#

Docker networks created with docker network create do not survive an Unraid restart by default because the Docker service recreates its environment from scratch on boot.

The reliable way to ensure core_net always exists is to create it in a Docker Compose file that runs on startup. Create a dedicated compose file for your shared infrastructure:

mkdir -p /mnt/user/compose/core
nano /mnt/user/compose/core/docker-compose.yml

Paste the following into that file:

networks:
  core_net:
    driver: bridge
    name: core_net

Save and close the file (Ctrl+X, then Y, then Enter).

If you are using the Compose Manager plugin in Unraid, add this stack and set it to auto-start. When Unraid boots, Compose Manager will bring up this stack first, which creates core_net before any other containers start.

Lab Notes & Troubleshooting

#

Container can’t reach another container by name. Confirm both containers are on core_net by running docker network inspect core_net and checking the Containers section. If one is missing, connect it with docker network connect core_net CONTAINER_NAME.

“network not found” error when starting a compose stack. The core_net network does not exist yet. Either run docker network create core_net manually, or bring up your core infrastructure compose stack first.

“network core_net already exists” error in Docker Compose. You are missing external: true in the networks block of your compose file. Add it as shown in Step 7.

Container is on core_net but still can’t connect to a service. The network connection is working, but the service itself may not be listening on the right interface or port. Check the container logs with docker logs CONTAINER_NAME for errors.

I need to remove core_net and start over. First disconnect all containers from it (docker network disconnect core_net CONTAINER_NAME for each one), then delete it with docker network rm core_net. You can recreate it fresh with docker network create core_net.

Summary

#

You now have a custom Docker network called core_net running on your Unraid server. Any container connected to this network can reach any other container on it by name, without needing to expose ports or rely on IP addresses that change. Going forward, all shared services like databases, caches, and reverse proxies will join core_net so they can communicate privately and securely.

In the next tutorial, you will use Docker Compose on Unraid to organize your container stacks into structured files, making them easier to manage, version, and reproduce.

Next Step: Docker Compose on Unraid