pythonicvarun/containerscope repository overview

⁠ContainerScope

A lightweight, real-time Docker container log viewer with a modern web interface.

⁠Features

• 🔴 Real-time log streaming via WebSocket
• 🐳 Auto-discovers all running Docker containers
• 🔍 Filter logs with instant search
• 📜 Separate stdout/stderr viewing
• 🎯 Follow mode to auto-scroll to latest logs
• 🖥️ Clean, modern UI with dark theme
• ⚡ Lightweight - single binary, minimal footprint
• 🔒 Secure authentication with session-based login
• 🛡️ Rate limiting to prevent brute force attacks

⁠Quick Start

⁠Using Docker (Recommended)

docker run -d \
  --name containerscope \
  -p 4000:4000 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e CONTAINER_SCOPE_PASSWORD=your_secure_password \
  pythonicvarun/containerscope:latest

Then open http://localhost:4000⁠ and login with:

• Username: admin (default)
• Password: your configured password

⁠Building from Source

Requirements:

• Go 1.26 or later

# Clone the repository
git clone https://github.com/PythonicVarun/containerscope.git
cd containerscope

# Build the binary
go build -o containerscope ./cmd/containerscope

# Run (requires access to Docker socket and password)
CONTAINER_SCOPE_PASSWORD=your_secure_password ./containerscope

⁠Configuration

⁠Architecture

containerscope/
├── cmd/containerscope/    # Application entry point
├── internal/
│   ├── app/               # HTTP server and handlers
│   ├── auth/              # Authentication and session management
│   ├── dockerapi/         # Docker API client
│   └── ws/                # WebSocket handling
└── public/                # Static web UI assets

⁠Authentication

ContainerScope uses secure session-based authentication:

• Session cookies: HttpOnly, SameSite=Strict, optional Secure flag
• Password hashing: bcrypt with cost 10
• Session tokens: 32 bytes of cryptographically secure random data
• Session expiry: 24 hours
• Rate limiting: 5 failed attempts trigger 15-minute lockout

All API endpoints and WebSocket connections require authentication. The login page is the only publicly accessible route.

⁠Usage

1. Start ContainerScope using one of the methods above
2. Login at the authentication page http://localhost:4000
3. Select a container from the sidebar to view its logs
4. Use the toolbar to:
   • Filter logs with the search bar
   • Toggle stderr visibility
   • Enable/disable follow mode
   • Clear the log buffer
5. Logout using the button in the header when done

⁠Security Considerations

ContainerScope requires read-only access to the Docker socket (/var/run/docker.sock). This is necessary to:

• List running containers
• Stream container logs

Important:

• The Docker socket provides access to the Docker daemon. Only run ContainerScope in trusted environments.
• Always set a strong password for the CONTAINER_SCOPE_PASSWORD environment variable.
• Enable CONTAINER_SCOPE_SECURE_COOKIES=true when deploying behind HTTPS.

⁠Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate.

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Acknowledgments

• Built with Go⁠