¶ 🛡️ SSH Tunnel - Secure Remote Access via SSH Tunnels
¶ 🚀 Quick Start
For a fast setup, run:
docker run -d -e SSH_HOST=your-server -e SSH_USER=user \
-v ~/.ssh/id_rsa:/tmp/id_rsa:ro ripleybooya/ssh-tunnel
¶ 📌 Why this image?
This container was created to securely expose remote services via SSH tunnels.
Instead of exposing databases or other services to the public internet, this container allows you to create secure SSH tunnels inside a Docker network.
¶ 🔥 Use Cases:
- Securely connect to remote databases (PostgreSQL, MySQL, MariaDB).
- Access internal services (Redis, Elasticsearch, APIs) via SSH.
- Securely tunnel any service without exposing it publicly.
¶ 🚀 How to Use
¶ 1️⃣ Run with docker run
docker run -d --name ssh-tunnel \
-e SSH_HOST="your-server.com" \
-e SSH_USER="your-username" \
-e REMOTE_PORTS="127.0.0.1:5432 127.0.0.1:443" \
-e LOCAL_PORTS="15432 8443" \
-v /path/to/id_rsa:/tmp/id_rsa:ro \
--network=my_docker_network \
ripleybooya/ssh-tunnel
📌 Explanation:
SSH_HOST: The remote server where SSH tunnels will be established.SSH_USER: The SSH user on the remote server.REMOTE_PORTS: Ports from the remote server (format:127.0.0.1:PORT).LOCAL_PORTS: Ports inside the Docker container (mapped toREMOTE_PORTS).LOGROTATE_FREQUENCY: Logrotate Frequency (default todaily).LOGROTATE_ROTATE: Logrotate rotation to keep (default to7).LOGROTATE_COMPRESS: Logrotate compression (default tocompress).-v /path/to/id_rsa:/tmp/id_rsa:ro: Mounts your SSH key securely (using/tmp/id_rsafor better permissions).
¶ 2️⃣ Using docker-compose.yml
For easier management, use Docker Compose:
¶ 2️⃣.1️⃣ Using a Custom Network (Recommended)
version: '3.8'
services:
ssh-tunnel:
image: ripleybooya/ssh-tunnel
container_name: ssh-tunnel
restart: always
networks:
- internal
environment:
SSH_HOST: "your-server.com"
SSH_USER: "your-username"
REMOTE_PORTS: "127.0.0.1:5432 127.0.0.1:443"
LOCAL_PORTS: "15432 8443"
volumes:
- /path/to/id_rsa:/tmp/id_rsa:ro
networks:
internal:
driver: bridge
¶ 2️⃣.2️⃣ Using Host Network Mode (Alternative)
If you need the ports to be accessible outside Docker, use network_mode: host :
version: '3.8'
services:
ssh-tunnel:
image: ripleybooya/ssh-tunnel
container_name: ssh-tunnel
restart: always
network_mode: host # Uses the host network instead of a Docker network
environment:
SSH_HOST: "your-server.com"
SSH_USER: "your-username"
REMOTE_PORTS: "127.0.0.1:5432 127.0.0.1:443"
LOCAL_PORTS: "15432 8443"
volumes:
- /path/to/id_rsa:/tmp/id_rsa:ro
📌 Which mode to choose?
- ✅ Custom network (default) → If services are inside Docker.
- ✅ Host mode → If you want to expose the tunnel outside Docker.
¶ 🚀 Using with Tailscale
This version integrates Tailscale VPN for secure remote access & exposes the port to your tailnet.
To use the Tailscale version you need to append the tailscale tag: ripleybooya/ssh-tunnel:tailscale
¶ Run with docker run
docker run -d --name ssh-tunnel-tailscale \
-e SSH_HOST="your-server.com" \
-e SSH_USER="your-username" \
-e REMOTE_PORTS="127.0.0.1:5432 127.0.0.1:443" \
-e LOCAL_PORTS="15432 8443" \
-e TAILSCALE_AUTH_KEY="your-tailscale-auth-key" \
-v /path/to/id_rsa:/tmp/id_rsa:ro \
-v /path/to/tailscale/persistent/data:/var/lib/tailscale # Persistent Tailscale state, needed after initial key expiration
-p 15432:15432 # (Optional) Also expose port on local network.
-p 8443:8443 # (Optional) Also expose port on local network.
--cap-add=NET_ADMIN \
--device /dev/net/tun:/dev/net/tun \
ripleybooya/ssh-tunnel:tailscale
📌 Explanation:
SSH_HOST: The remote server where SSH tunnels will be established.SSH_USER: The SSH user on the remote server.REMOTE_PORTS: Ports from the remote server (format:127.0.0.1:PORT).LOCAL_PORTS: Ports inside the Docker container (mapped toREMOTE_PORTS).TAILSCALE_AUTH_KEY: Initial Tailscale Authentication Key (optionnal)
/!\ Must be empty if you want to use TAILSCALE_PARAM.
(You can generate a key here: Tailscale Keys)
TAILSCALE_PARAM: full control overtailscale upoptions. Usefull if you plan to automate deployment with OAuth Client etc.
(tailscale up command parameters & Registering new nodes using OAuth credentials).
LOGROTATE_FREQUENCY: Logrotate Frequency (default todaily).LOGROTATE_ROTATE: Logrotate rotation to keep (default to7).LOGROTATE_COMPRESS: Logrotate compression (default tocompress).-v /path/to/id_rsa:/tmp/id_rsa:ro: Mounts your SSH key securely (using/tmp/id_rsafor better permissions).-v /path/to/tailscale/persistent/data:/var/lib/tailscale: Required for Persistent Tailscale state. (optionnal)
- Exposing ports with
-p PORT:PORTis not mandatory to access the ports from a docker network or your Tailnet.- Only usefull if you want your ports to be exposed to the local network.
Without Registering new nodes using OAuth credentials or a persistent storage for
/var/lib/tailscaleafter the initial key expire, the container will not be able to connect to your Tailnet.
¶ Using docker-compose.yml
version: '3.8'
services:
ssh-tunnel-tailscale:
image: ripleybooya/ssh-tunnel:tailscale
container_name: ssh-tunnel-tailscale
restart: always
environment:
SSH_HOST: "your-server.com"
SSH_USER: "your-username"
REMOTE_PORTS: "127.0.0.1:5432 127.0.0.1:3306"
LOCAL_PORTS: "5432 3306"
TAILSCALE_PARAM: "--reset --auth-key='tskey-client-XXXXXXXXXXXXXXXXX-YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY?ephemeral=true&preauthorized=true' --advertise-tags=tag:dba --hostname=TS-DB-ACCESS"
volumes:
- /path/to/id_rsa:/tmp/id_rsa:ro
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
📌 Explanation:
SSH_HOST: The remote server where SSH tunnels will be established.SSH_USER: The SSH user on the remote server.REMOTE_PORTS: Ports from the remote server (format:127.0.0.1:PORT).LOCAL_PORTS: Ports inside the Docker network (mapped toREMOTE_PORTS).TAILSCALE_AUTH_KEY: Initial Tailscale Authentication Key (optionnal)
/!\ Must be empty if you want to use TAILSCALE_PARAM.
(You can generate a key here: Tailscale Keys)
TAILSCALE_PARAM: full control overtailscale upoptions. Usefull if you plan to automate deployment with OAuth Client etc.
(tailscale up command parameters & Registering new nodes using OAuth credentials).
LOGROTATE_FREQUENCY: Logrotate Frequency (default todaily).LOGROTATE_ROTATE: Logrotate rotation to keep (default to7).LOGROTATE_COMPRESS: Logrotate compression (default tocompress)./path/to/id_rsa:/tmp/id_rsa:ro: Mounts your SSH key securely (using/tmp/id_rsafor better permissions).ssh_tunnel_tailscale_data:/var/lib/tailscale: Required for Persistent Tailscale state. (optionnal)
- Exposing ports with "
ports:" is not mandatory to access the ports from a docker network or your Tailnet.- Only usefull if you want your ports to be exposed to the local network.
Without Registering new nodes using OAuth credentials or a persistent storage for
/var/lib/tailscaleafter the initial key expire, the container will not be able to connect to your Tailnet.
¶ 🔄 Automated Daily Builds for Security & Performance
This Docker image is rebuilt automatically every day to ensure it always includes:
- ✅ The latest security updates from the Alpine base image.
- ✅ The most recent versions of system dependencies.
- ✅ Potential performance improvements from the build process.
⚠ Note: These daily builds do not necessarily mean changes to the project itself.
If you're looking for actual updates to the codebase, please refer to the commit history or the release tags.
¶ 📌 Why use this image?
- ✅ Secure: No need to expose services publicly.
- ✅ Simple: Just set environment variables and run.
- ✅ Multi-Arch: Works on x86_64 (Intel/AMD) and ARM64 (Oracle Cloud, Raspberry Pi, etc.).
- ✅ Lightweight: Uses Alpine Linux for minimal resource usage.
¶ 📦 Pull & Run
docker pull ripleybooya/ssh-tunnel
docker run --rm -it ripleybooya/ssh-tunnel sh -c "uname -m && echo 'Container is working'"
🚀 Now your remote services are accessible through secure SSH tunnels!
¶ 🔖 Tags & Keywords
This image can be used for:
- 🛡️ SSH Tunneling
- 🔌 Networking & Proxy
- 🔒 Security & Encryption
- 🗄️ Database Access (PostgreSQL, MySQL, MariaDB, etc.)
- 🏗️ Remote Service Exposure in Docker
¶ 📜 Third-Party Licenses
This project is based on:
- Alpine Linux - MIT License
- OpenSSH - BSD License
- Tailscale - MIT License
- Docker - Apache 2.0 License
¶ 📜 License
This project is licensed under the MIT License.
You are free to use, modify, and distribute it.
Read the full license here.
¶ 🤖 AI Assistance & Acknowledgment
- This project was built with the help of an AI-powered assistant (LLM) to improve structure, efficiency, and documentation clarity.
- A big thank to Xénophée for the inspiration that started this project.
¶ 🏗️ How to Build the Image
If you want to build this image yourself, follow these steps:
¶ 1️⃣ Clone the Repository
git clone https://github.com/RipleyBooya/ssh-tunnel.git
cd ssh-tunnel
¶ 2️⃣ Build for Multi-Architecture (amd64 & arm64)
docker buildx build --platform linux/amd64,linux/arm64 \
-t dockerhub_account/ssh-tunnel:latest \
--push .
¶ 3️⃣ Verify the Image
docker buildx imagetools inspect dockerhub_account/ssh-tunnel:latest
¶ 4️⃣ Test Locally
docker run --rm -it dockerhub_account/ssh-tunnel sh -c "uname -m && echo 'Container is running successfully'"
Now your image is built and ready for use! 🚀
¶ 🔗 Project Links & Contributions
This project is open-source and welcomes contributions!
- 🛠 Source Code & Issues: GitHub Repository
- 🐳 Docker Hub Page: Docker Image
- 🇫🇷 Version française (WikiJS): ltgs.wiki (FR)
- 🇺🇸 English version (WikiJS): ltgs.wiki (EN)
If you find any issues or have suggestions, feel free to open a GitHub issue or contribute! 🚀