https://github.com/fm-labs/rdocker
Simple, fast, and secure way to connect to remote Docker daemons
https://github.com/fm-labs/rdocker
docker docker-cli remote-control remote-management
Last synced: 2 days ago
JSON representation
Simple, fast, and secure way to connect to remote Docker daemons
- Host: GitHub
- URL: https://github.com/fm-labs/rdocker
- Owner: fm-labs
- Created: 2025-04-13T09:51:16.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-02T19:23:52.000Z (6 months ago)
- Last Synced: 2025-11-02T21:13:40.066Z (6 months ago)
- Topics: docker, docker-cli, remote-control, remote-management
- Language: Shell
- Homepage: https://fm-labs.github.io/rdocker/
- Size: 71.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# rdocker
Simple, fast, and secure way to connect to remote Docker daemons.
## How it works
Under the hood `ssh`, `autossh`, `socat` and `docker` commands
are wrapped to create a secure and stable tunnel to a remote Docker daemon.
The `rdocker` script creates tunnels the remote docker daemon socket to a local socket
and (optionally) exposes the socket via a TCP proxy to the controlling host (localhost),
which allows you to run docker commands on the remote machine as if they were running locally.
## Features
- ð **Secure**: Uses SSH to connect to remote Docker daemon.
- ð **Fast**: Uses a permanent tunnel and the `docker` CLI to interact with the remote Docker daemon.
- ðŠ **Resilient**: Automatically reconnects to the remote Docker daemon if the connection is lost.
- ðģ **Simple**: Spin up a tunnel to the remote Docker daemon with a single command.
- ðŠķ **Lightweight**: No need to install any additional software on the remote server.
- ðĶ **Compact**: Only a few hundred lines of code. Docker image is less than 50MB.
- ðŧ **Portable**: Can be run from any machine with SSH access to the remote server.
- â
**Easy to use**: Just use `rdocker` command instead of `docker` to interact with remote Docker daemon.
## Getting Started
### Prerequisites
- ðŧ Local machine
- â
Docker CLI installed on your local machine.
- â
SSH client installed on your local machine.
- â
SSH access to the remote server.
- ð Remote server
- â
Docker Engine installed on the remote server.
- â
SSH server installed on the remote server.
### Create a rdocker configuration
To create a `rdocker` configuration, run the following command:
```bash
mkdir -p ~/.rdocker
cat < ~/.rdocker/remote0.env
RDOCKER_REMOTE_HOST=remote0.example.com
RDOCKER_REMOTE_USER=ubuntu
RDOCKER_REMOTE_SSH_KEY=~/.ssh/id_rsa
RDOCKER_TCP_ENABLE=1
RDOCKER_TCP_PORT=12345
EOF
```
### Start rdocker tunnel
To start a `rdocker` tunnel to a remote Docker daemon, run the following command:
```bash
RDOCKER_CONTEXT=remote0 ./rdocker tunnel-up
# Outputs:
#-----------------------
#* RDOCKER_CONTEXT: remote0
#* RDOCKER_REMOTE_HOST: remote0.example.com
#* RDOCKER_REMOTE_USER: ubuntu
#* RDOCKER_REMOTE_SOCKET: /var/run/docker.sock
#* RDOCKER_LOCAL_SOCKET: /tmp/rdocker-docker.remote0.sock
#* RDOCKER_HOST: unix:///tmp/rdocker-docker.remote0.sock
#-----------------------
#ð SSH tunnel established to remote0.example.com
#ð°ïļ Local socket: /tmp/rdocker-docker.remote0.sock
#ð°ïļ Local tcp proxy: localhost:12345
#ð -> DOCKER_HOST=unix:///tmp/rdocker-docker.remote0.sock
#ð -> DOCKER_HOST=tcp://localhost:12345
#Successfully created context "remote0"
#Successfully created context "remote0-tcp"
#ðĨïļ -> docker context use remote0
#ðĨïļ -> docker context use remote0-tcp
#Probing connection ...
#CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
#Docker connection is working
#Press Ctrl+C to close tunnel and exit.
```
### Access the remote Docker daemon
From another terminal, you can now access the remote Docker daemon using either the `rdocker` or `docker` cli command:
#### Using rdocker
```bash
RDOCKER_CONTEXT=remote0 ./rdocker ps
```
#### Using docker
```bash
DOCKER_HOST=unix:///tmp/rdocker-docker.remote0.sock docker ps
```
#### Using docker context
```bash
docker context use remote0
docker ps
```
### Start rdocker tunnel using Docker
The docker instances will expose the remote docker socket to the local machine via TCP.
This allows you to run docker commands on the remote machine as if they were running locally.
```bash
docker run -it --rm \
-v ~/.ssh:/home/rdocker/.ssh \
-e RDOCKER_REMOTE_HOST=remote0.example.com \
-e RDOCKER_REMOTE_USER=ubuntu \
-p 12345:12345 \
fmlabs/rdocker:latest
```
## Environment Variables
- `RDOCKER_CONTEXT`: Rdocker context. Required.
- `RDOCKER_REMOTE_HOST`: Remote host to connect to. Required.
- `RDOCKER_REMOTE_USER`: Remote user to connect to. Required.
- `RDOCKER_HOME`: Base directory for `rdocker` configurations. Default is `~/.rdocker`.
- `RDOCKER_DEBUG`: Enable debug mode. Default is `0`.
- `RDOCKER_TCP_ENABLE`: Enable TCP proxy for the tunneled docker socket. Default is `0`.
- `RDOCKER_TCP_PORT`: TCP port. Default is `12345`.
## Caveats
### Limited docker compose support
The `rdocker` script does not fully support `docker-compose` commands (yet).
Especially the `docker-compose up` command is tricky, when using
file mounts, as the `docker-compose` command will try to mount the files
from the local machine to the remote machine, which will not work.