162 lines
4.1 KiB
Markdown
162 lines
4.1 KiB
Markdown
# MGM Image
|
|
|
|
A lightweight Alpine-based Docker image that provides SSH and web terminal access through ttyd. Perfect for development environments, remote debugging, or containerized workspaces.
|
|
|
|
## Features
|
|
|
|
- 🐧 **Alpine Linux** - Minimal base image for small footprint
|
|
- 🔒 **SSH Server** - Full SSH access on port 22
|
|
- 🌐 **Web Terminal** - Browser-based terminal via ttyd on port 1234
|
|
- 🐚 **Fish Shell** - Modern shell with auto-suggestions and syntax highlighting
|
|
- 🔧 **Development Tools** - Git, curl, wget, htop, vim, nano included
|
|
- 🚦 **Signal Handling** - Proper Docker signal propagation for graceful shutdowns
|
|
|
|
## Quick Start
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `TTYD_PASSWORD` | ✅ Yes | - | Password for web terminal authentication |
|
|
|
|
### Running the Container
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name mgm-container \
|
|
-p 2222:22 \
|
|
-p 1234:1234 \
|
|
-e TTYD_PASSWORD=your_secure_password \
|
|
gitea.ceperka.net/rosti/mgm:dev
|
|
```
|
|
|
|
### Accessing Services
|
|
|
|
- **SSH**: `ssh root@localhost -p 2222`
|
|
- **Web Terminal**: http://localhost:1234 (username: `tty`, password: your `TTYD_PASSWORD`)
|
|
|
|
## Building
|
|
|
|
This project uses [Task](https://taskfile.dev) for build automation.
|
|
|
|
### Prerequisites
|
|
|
|
- Docker
|
|
- Task (optional, you can use docker commands directly)
|
|
|
|
### Build Commands
|
|
|
|
```bash
|
|
# Build the image
|
|
task build
|
|
|
|
# Push to registry
|
|
task push
|
|
|
|
# Or use Docker directly
|
|
docker build -t gitea.ceperka.net/rosti/mgm:dev .
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The container runs two services managed by a bash-based process supervisor:
|
|
|
|
```
|
|
entrypoint.sh
|
|
├── service.ssh.sh # SSH daemon (/usr/sbin/sshd -D)
|
|
└── service.ttyd.sh # Web terminal (ttyd + fish shell)
|
|
```
|
|
|
|
### Process Management
|
|
|
|
- **Signal Handling**: SIGTERM/SIGINT signals are properly propagated to child processes
|
|
- **Graceful Shutdown**: Services receive SIGTERM first, then SIGKILL after timeout
|
|
- **Process Monitoring**: Parent process waits for all children and handles exits
|
|
- **No Dependencies**: Pure bash implementation, no external process managers
|
|
|
|
### Security Considerations
|
|
|
|
- SSH is configured to allow root login with password authentication
|
|
- ttyd is bound to `127.0.0.1` (localhost) for security - use reverse proxy if needed
|
|
- Set a strong `TTYD_PASSWORD` as it protects web terminal access
|
|
- Consider using SSH keys instead of passwords in production
|
|
|
|
## Development
|
|
|
|
### File Structure
|
|
|
|
```
|
|
├── Dockerfile # Alpine-based image definition
|
|
├── entrypoint.sh # Main entrypoint with process management
|
|
├── service.ssh.sh # SSH service wrapper
|
|
├── service.ttyd.sh # ttyd service wrapper
|
|
├── Taskfile.yml # Build automation
|
|
└── README.md # This file
|
|
```
|
|
|
|
### Customization
|
|
|
|
You can extend this image for your specific needs:
|
|
|
|
```dockerfile
|
|
FROM gitea.ceperka.net/rosti/mgm:dev
|
|
|
|
# Add your tools
|
|
RUN apk add --no-cache python3 nodejs
|
|
|
|
# Copy your configurations
|
|
COPY custom-config/ /etc/
|
|
|
|
# Set your working directory
|
|
WORKDIR /workspace
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Container won't start
|
|
|
|
1. Check if `TTYD_PASSWORD` is set:
|
|
```bash
|
|
docker logs <container-name>
|
|
```
|
|
|
|
2. Verify ports aren't already in use:
|
|
```bash
|
|
netstat -tulpn | grep -E ':(22|1234)'
|
|
```
|
|
|
|
### SSH connection refused
|
|
|
|
1. Check if SSH service is running:
|
|
```bash
|
|
docker exec <container-name> ps aux | grep sshd
|
|
```
|
|
|
|
2. Verify SSH host keys were generated:
|
|
```bash
|
|
docker exec <container-name> ls -la /etc/ssh/ssh_host_*
|
|
```
|
|
|
|
### Web terminal not accessible
|
|
|
|
1. Check ttyd service status:
|
|
```bash
|
|
docker exec <container-name> ps aux | grep ttyd
|
|
```
|
|
|
|
2. Verify ttyd is listening:
|
|
```bash
|
|
docker exec <container-name> netstat -tulpn | grep 1234
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
This project is open source. Please check the license file for more details.
|