Remote Docker on NAS

Overview

Run Docker on a remote NAS/server controlled from your laptop via SSH — no local Docker daemon needed. Uses crane (~11MB) to pull images as tarballs and DOCKER_HOST=ssh:// to send commands to the remote daemon.

Architecture

Laptop (control plane)                NAS/Server (execution)
──────────────────────                ────────────────────────
docker-compose.yml (local)            Docker daemon
Makefile (local)              ──SSH──▶ Containers run here
source code (local)                   Data stored here
crane pull → .tar (local)             docker load → images here

Prerequisites

Laptop:

• crane — lightweight image puller, no daemon needed

  brew install crane
  

• docker CLI only (no Docker Desktop / OrbStack needed)
• SSH access to NAS (~/.ssh/config configured)

NAS/Server:

• Docker daemon running
• Your user in the docker group

  sudo usermod -aG docker <nas-user>
  # Log out and back in for group to take effect
  # Verify: groups | grep docker
  

Setup

Set DOCKER_HOST to route all docker commands via SSH:

export DOCKER_HOST=ssh://<nas-host>

# Verify
docker info

Add to shell profile for persistence:

# ~/.zshrc or ~/.bashrc
export DOCKER_HOST=ssh://<nas-host>

Image Workflow

When the NAS cannot reach Docker Hub (firewall/network), pull images on the laptop with crane and load them onto the NAS:

# 1. Pull image as tarball (runs on laptop, no daemon needed)
crane pull nginx:alpine /tmp/nginx-alpine.tar

# 2. Load onto NAS (DOCKER_HOST routes this via SSH)
docker load -i /tmp/nginx-alpine.tar

# 3. Run
docker run -d --name web -p 8080:80 nginx:alpine

Key Gotchas

The #1 mistake: Using relative volume paths like ./html:/usr/share/nginx/html. This resolves on the NAS, not your laptop. Use absolute NAS paths.

Docker Compose Template

services:
  web:
    image: nginx:alpine
    ports:
      - "8888:80"
    volumes:
      - /home/<nas-user>/project/html:/usr/share/nginx/html:ro
    restart: unless-stopped

Deploy workflow:

# 1. Copy source files to NAS
scp -r ./html <nas-host>:/home/<nas-user>/project/

# 2. Pull and load images
crane pull nginx:alpine /tmp/nginx-alpine.tar
docker load -i /tmp/nginx-alpine.tar

# 3. Start (compose file is local, execution is remote)
docker compose up -d

Makefile Template

DOCKER_HOST := ssh://<nas-host>
NAS_PROJECT := /home/<nas-user>/project
export DOCKER_HOST

IMAGES := nginx:alpine

.PHONY: pull load sync up down ps logs clean

pull:
	@for img in $(IMAGES); do \
		echo "Pulling $$img..."; \
		crane pull $$img /tmp/$$(echo $$img | tr '/:' '-').tar; \
	done

load:
	@for img in $(IMAGES); do \
		tarfile=/tmp/$$(echo $$img | tr '/:' '-').tar; \
		echo "Loading $$tarfile..."; \
		docker load -i $$tarfile; \
	done

sync:
	scp -r ./html <nas-host>:$(NAS_PROJECT)/

up: pull load sync
	docker compose up -d

down:
	docker compose down

ps:
	docker compose ps

logs:
	docker compose logs -f

clean: down
	docker compose rm -f
	docker image prune -f

Reference Stacks

Ready-to-deploy compose files in references/. Replace <nas-host> and <nas-user> with your values.

Quick deploy any stack:

# Example: deploy FreshRSS
crane pull freshrss/freshrss:latest /tmp/freshrss.tar
crane pull postgres:16-alpine /tmp/postgres-16-alpine.tar
docker load -i /tmp/freshrss.tar
docker load -i /tmp/postgres-16-alpine.tar
docker compose -f references/freshrss.yml up -d

Multi-service architecture (recommended for production):

Nginx Proxy Manager (:80/:443)
  ├── FreshRSS    → localhost:8280
  ├── BookLore    → localhost:6060
  └── Other apps  → localhost:XXXX

Troubleshooting