Name	Name	Last commit message	Last commit date
Latest commit History 4 Commits
root	root
.gitignore	.gitignore
Dockerfile	Dockerfile
README.md	README.md
build	build
docker-compose.yml	docker-compose.yml

OpenSSH Docker Image

A production-ready OpenSSH server Docker image based on Debian Bookworm, designed for secure remote access, development environments, and CI/CD pipelines.

Features

Secure by Default: Password authentication disabled, public key authentication preferred
Flexible User Management: Customizable UID/GID for seamless host volume permissions
Persistent Configuration: All configs and host keys stored in /app volume
Development Tools: Includes git, golang, curl, wget, and common utilities
Timestamped Logging: Built-in log management with timestamps
Easy SSH Key Management: Multiple ways to inject public keys
Optional Sudo Access: Configurable sudo permissions
Small Footprint: Based on Debian Bookworm Slim

Quick Start

Using Docker Run

# Pull the image
docker pull ghcr.io/optimode/openssh:bookworm
# Create config directory
mkdir -p ./config/.ssh
# Add your SSH public key
cat ~/.ssh/id_rsa.pub > ./config/.ssh/authorized_keys
# Run the container
docker run -d \
 --name openssh \
 -p 2222:2222 \
 -v ./config:/app \
 -e USER_NAME=devuser \
 -e PUID=1000 \
 -e PGID=1000 \
 ghcr.io/optimode/openssh:bookworm
# Connect
ssh -p 2222 devuser@localhost

Using Docker Compose

Create a docker-compose.yml file:

services:
 openssh:
 image: ghcr.io/optimode/openssh:bookworm
 container_name: openssh
 restart: unless-stopped
 ports:
 - "2222:2222"
 volumes:
 - ./config:/app
 - ./workspace:/workspace
 environment:
 - TZ=Europe/Budapest
 - PUID=1000
 - PGID=1000
 - USER_NAME=devuser
 - SUDO_ACCESS=false
 - PASSWORD_ACCESS=false

Then run:

# Add your SSH public key
mkdir -p ./config/.ssh
cat ~/.ssh/id_rsa.pub > ./config/.ssh/authorized_keys
# Start the container
docker-compose up -d
# Connect
ssh -p 2222 devuser@localhost

Configuration

Environment Variables

User Configuration

Variable	Default	Description
`USER_NAME`	`app`	Username for SSH access
`PUID`	`911`	User ID (useful for matching host user permissions)
`PGID`	`911`	Group ID (useful for matching host group permissions)
`USER_HOME`	`/app`	User home directory
`USER_PASSWORD`	`<random>`	User password (auto-generated if not set)
`USER_PASSWORD_FILE`	-	Path to file containing password (Docker secrets)

SSH Configuration

Variable	Default	Description
`LISTEN_PORT`	`2222`	SSH server listening port
`PASSWORD_ACCESS`	`false`	Enable/disable password authentication
`PUBLIC_KEY`	-	SSH public key (single key as string)
`PUBLIC_KEY_FILE`	-	Path to file containing a public key
`PUBLIC_KEY_DIR`	-	Path to directory containing multiple key files

Access Control

Variable	Default	Description
`SUDO_ACCESS`	`false`	Grant sudo privileges to the user
`UMASK`	`022`	Default umask for file creation

System Configuration

Variable	Default	Description
`TZ`	`UTC`	Timezone (e.g., `Europe/Budapest`, `America/New_York`)

Volume Mounts

Path	Purpose
`/app`	Required - Persistent storage for SSH config, host keys, and user data
`/workspace`	Optional - Additional workspace directory

Ports

Port	Protocol	Description
`2222`	TCP	SSH server port (configurable via `LISTEN_PORT`)

SSH Key Management

There are multiple ways to provide SSH public keys for authentication:

Method 1: Authorized Keys File (Recommended)

mkdir -p ./config/.ssh
cat ~/.ssh/id_rsa.pub > ./config/.ssh/authorized_keys
chmod 600 ./config/.ssh/authorized_keys

Method 2: Environment Variable

environment:
 - PUBLIC_KEY=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...

Method 3: Key File

environment:
 - PUBLIC_KEY_FILE=/secrets/ssh-key.pub
volumes:
 - ./my-key.pub:/secrets/ssh-key.pub:ro

Method 4: Key Directory

environment:
 - PUBLIC_KEY_DIR=/secrets/keys
volumes:
 - ./keys:/secrets/keys:ro

Multiple methods can be used simultaneously - all keys will be added to authorized_keys.

Advanced Usage Examples

Example 1: Development Environment with Sudo

services:
 devssh:
 image: optimode/openssh:bookworm
 container_name: devssh
 ports:
 - "2222:2222"
 volumes:
 - ./config:/app
 - ./projects:/workspace
 - /var/run/docker.sock:/var/run/docker.sock # Docker-in-Docker
 environment:
 - USER_NAME=developer
 - PUID=1000
 - PGID=1000
 - SUDO_ACCESS=true
 - PASSWORD_ACCESS=false
 - TZ=America/New_York

Example 2: Password Authentication Enabled

services:
 openssh:
 image: optimode/openssh:bookworm
 container_name: openssh-pass
 ports:
 - "2222:2222"
 volumes:
 - ./config:/app
 environment:
 - USER_NAME=testuser
 - USER_PASSWORD=SecurePassword123
 - PASSWORD_ACCESS=true
 - SUDO_ACCESS=false

Example 3: Multiple Users with Docker Secrets

services:
 openssh:
 image: optimode/openssh:bookworm
 container_name: openssh-secure
 ports:
 - "2222:2222"
 volumes:
 - ./config:/app
 secrets:
 - ssh_password
 environment:
 - USER_NAME=admin
 - USER_PASSWORD_FILE=/run/secrets/ssh_password
 - PASSWORD_ACCESS=true
secrets:
 ssh_password:
 file: ./secrets/password.txt

Example 4: Custom Port and Timezone

services:
 openssh:
 image: optimode/openssh:bookworm
 container_name: openssh-custom
 ports:
 - "2200:2200"
 volumes:
 - ./config:/app
 environment:
 - LISTEN_PORT=2200
 - USER_NAME=sshuser
 - TZ=Asia/Tokyo
 - PUID=1001
 - PGID=1001

Building from Source

# Clone the repository
git clone https://github.com/optimode/docker-openssh.git
cd docker-openssh
# Build the image
./build
# Or use docker build directly
docker build -t optimode/openssh:bookworm .

Directory Structure in Container

/app/
├── .ssh/
│ └── authorized_keys # SSH public keys
├── sshd/
│ └── sshd_config # OpenSSH server configuration
├── ssh_host_keys/ # Persistent host keys
└── logs/
 └── openssh/
 └── sshd.log # SSH server logs with timestamps

Logging

Logs are stored in /app/logs/openssh/sshd.log with timestamps in format [YYYY-MM-DD HH:MM:SS TZ].

View logs:

# Real-time logs
docker logs -f openssh
# Persistent log file
docker exec openssh tail -f /app/logs/openssh/sshd.log

Troubleshooting

Connection Refused

Problem: Cannot connect to SSH server

Solutions:

Check if container is running: docker ps
Verify port mapping: docker port openssh
Check firewall rules on host
Verify SSH service is running: docker exec openssh ps aux | grep sshd

Permission Denied (publickey)

Problem: Authentication fails with public key

Solutions:

Verify key is in authorized_keys: docker exec openssh cat /app/.ssh/authorized_keys
Check key permissions: Should be 600 for authorized_keys, 700 for .ssh
Ensure the correct private key is being used: ssh -i ~/.ssh/id_rsa -p 2222 user@localhost
Check logs: docker logs openssh

Permission Issues with Volumes

Problem: Files in mounted volumes have wrong ownership

Solutions:

Set PUID and PGID to match your host user:

id -u # Get your UID
id -g # Get your GID

Update docker-compose.yml with correct values
Restart container: docker-compose down && docker-compose up -d

Can't Write to Workspace

Problem: User cannot write to /workspace directory

Solutions:

Ensure proper ownership of host directory:

sudo chown -R 1000:1000 ./workspace # Use your PUID:PGID

Or set permissions to allow write access:
```
chmod -R 755 ./workspace
```

Sudo Not Working

Problem: Sudo commands fail despite SUDO_ACCESS=true

Solutions:

Verify environment variable is set: docker exec openssh env | grep SUDO
Check sudoers file: docker exec openssh cat /etc/sudoers | grep app
If password required, ensure USER_PASSWORD is set
Restart container after changing SUDO_ACCESS

Security Considerations

Disable Password Authentication: Always use key-based authentication in production
Use Strong Keys: Generate keys with ssh-keygen -t ed25519 or ssh-keygen -t rsa -b 4096
Limit Sudo Access: Only enable SUDO_ACCESS=true when necessary
Firewall Rules: Restrict SSH port access to known IPs
Regular Updates: Keep the image updated for security patches
Monitor Logs: Regularly check /app/logs/openssh/sshd.log for suspicious activity
Use Docker Secrets: For sensitive data like passwords, use Docker secrets instead of environment variables

Version Information

Base Image: debian:bookworm-slim
OpenSSH Version: 8.4+
Exposed Port: 2222 (default)

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Optimode (Laszlo Malina)

optimode/openssh

Folders and files

Latest commit

History

Repository files navigation

OpenSSH Docker Image

Features

Quick Start

Using Docker Run

Using Docker Compose

Configuration

Environment Variables

User Configuration

SSH Configuration

Access Control

System Configuration

Volume Mounts

Ports

SSH Key Management

Method 1: Authorized Keys File (Recommended)

Method 2: Environment Variable

Method 3: Key File

Method 4: Key Directory

Advanced Usage Examples

Example 1: Development Environment with Sudo

Example 2: Password Authentication Enabled

Example 3: Multiple Users with Docker Secrets

Example 4: Custom Port and Timezone

Building from Source

Directory Structure in Container

Logging

Troubleshooting

Connection Refused

Permission Denied (publickey)

Permission Issues with Volumes

Can't Write to Workspace

Sudo Not Working

Security Considerations

Version Information

License

Contributing

Author

Links

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Packages 0

Uh oh!

Languages

Packages