mgm-image/README.md
Adam Štrauch 8c81737b87
Some checks failed
Build a dev image / build (push) Has been cancelled
Initial commit
2025-09-27 00:25:22 +02:00

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.