TDvorak/Containr
1
0
Fork 0
mirror of https://github.com/Dvorinka/Containr.git synced 2026-06-04 04:22:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Tomas Dvorak
2026-02-16 10:21:45 +01:00
parent ffa5489dc1
commit b62cf649d9
2 changed files with 273 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+273 -105
View File
@@ -1,119 +1,225 @@
# Containr - Container Management Platform
<p align="center">
<img src="./canvas_inspirational.png" alt="Containr Logo" width="200">
</p>
A modern container management platform with built-in Cloudflare tunnel support for easy deployment without domain configuration.
<h1 align="center">
Containr - Modern Container Management Platform
</h1>
<p align="center">
🚧 <strong>Work in Progress</strong> - Not yet fully functional, this is the default structure
</p>
<p align="center">
Deploy, manage, and scale containers with built-in Cloudflare tunnel support.
</p>
<p align="center">
<a href="#quick-start">Quick Start</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="#features">Features</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="#tech-stack">Tech Stack</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="#documentation">Documentation</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="#contributing">Contributing</a>
</p>
> **⚠️ Development Status**: This project is currently under active development and is **not yet ready for production use**. The current codebase represents the default structure and foundation for the container management platform. Many features are still being implemented and may not work as expected.
> **🚀 Inspired by Railway**: This project draws inspiration from [Railway](https://railway.app)'s seamless deployment experience and developer-friendly approach. The goal is to bring that same level of simplicity and power to self-hosted container management.
## Introduction
I built Containr because I was tired of complex container orchestration tools that required weeks of setup and deep expertise. You know how it is – Kubernetes clusters to configure, CI/CD pipelines to maintain, networking nightmares to debug, and that simple app deployment that somehow took three days to get running.
So I decided to build my own solution. Containr is basically the platform I wish I had – one place to deploy, manage, and scale containers without the complexity. It's open-source and self-hosted because I believe your infrastructure should belong to you, not some cloud provider.
It's like if Docker Compose, Traefik, and a modern dashboard had a baby. Built by one person (with AI's help), for anyone who's tired of container management being a mess.
### My Design Inspiration
I've always been a huge fan of **Portainer** – their clean, intuitive approach to container management just makes sense. Everything feels intentional and puts your containers first.
So yeah, Containr borrows heavily from that design philosophy. But I wrote every line of code from scratch – this isn't some fork or copy-paste job. I took that beautiful simplicity and tried to expand it into more of a comprehensive container platform with modern features.
### The AI-Assisted Journey
This project was built with **Windsurf SWE 1.5**.
Look, I'll be honest – I'm not the best DevOps engineer out there. But I really wanted to build something that solves real problems, and I think passion matters more than being perfect. Windsurf helped me figure out the hard stuff, learn new technologies, and actually build something I'm proud of.
As a solo dev, having an AI pair programmer made this whole thing possible. Go backend, React frontend, Docker orchestration – stuff I probably couldn't have tackled alone. It's pretty cool what you can create when humans and AI work together, even when you're still learning.
With Containr, your container deployments are centralized, scalable, and easy to manage, while remaining self-hosted so you maintain full control and privacy – just as it should be.
## Project Status
Containr is my labor of love – constantly evolving with core functionalities that I use every day. As a solo developer, I'm building this in the open, adding features based on real needs and feedback from fellow developers and DevOps engineers. The platform includes multiple services working together to create the container management hub I've always wanted.
Every feature you see is something I personally needed and use. Your feedback, bug reports, and feature ideas aren't just welcome – they're what help shape this tool into something that can help others manage their container infrastructure better too.
## Features
### Core Functionality
- **Container Management**: Deploy, start, stop, and restart containers with ease
- **Service Orchestration**: Manage multi-container applications with Docker Compose integration
- **Automatic SSL**: Built-in Let's Encrypt certificate management with Traefik
- **Cloudflare Tunnel**: Zero-config deployment with automatic public URLs
- **Web Dashboard**: Modern React-based interface for container management
- **Real-time Logs**: View and search container logs in real-time
### Advanced Features
- **Auto-scaling**: Automatic horizontal scaling based on resource metrics
- **Health Monitoring**: Comprehensive health checks and monitoring for all services
- **Resource Metrics**: CPU, memory, and network usage tracking
- **Preview Environments**: Automatic preview deployments for branches
- **Git Integration**: Connect repositories for automatic deployments
- **Environment Variables**: Secure management of application secrets and configuration
- **Database Management**: Built-in PostgreSQL and Redis with automated backups
- **Security Scanning**: Container vulnerability scanning and compliance reporting
### Deployment & Infrastructure
- **Multi-environment Support**: Development, staging, and production configurations
- **Load Balancing**: Intelligent traffic distribution with Traefik
- **Service Discovery**: Automatic service registration and discovery
- **Network Management**: Isolated networks and secure inter-service communication
- **Volume Management**: Persistent storage with automated backups
- **CI/CD Integration**: GitHub Actions and GitLab CI integration
### Security & Compliance
- **Authentication**: JWT-based authentication with OAuth2 support
- **Role-based Access Control**: Granular permissions for users and teams
- **Audit Logging**: Comprehensive audit trails for all actions
- **Data Encryption**: Encrypted storage for sensitive data
- **Security Scanning**: Automated vulnerability assessment
- **Compliance Reporting**: GDPR and SOC2 compliance frameworks
## Tech Stack
### Frontend
- **React + TypeScript** – Modern, reactive UI framework with type safety
- **Vite** – Fast build tool and development server with HMR
- **TailwindCSS** – Utility-first CSS framework for rapid UI development
- **@tanstack/react-query** – Powerful data fetching and state management
- **React Router** – Client-side routing for SPAs
- **@xyflow/react** – Interactive diagrams and visualizations
- **Recharts** – Beautiful charts and data visualization
- **Zustand** – Lightweight state management
### Backend Services
- **Main Backend (Go)** – Core API, container management, and business logic
- Gin web framework for HTTP routing
- GORM for database operations
- JWT authentication and authorization
- Docker SDK integration
- **Database Layer** – PostgreSQL for production data
- **Cache Layer** – Redis for session management and caching
- **Message Queue** – Background job processing
### Infrastructure & DevOps
- **Docker & Docker Compose** – Containerized deployment
- **Traefik** – Reverse proxy with automatic SSL
- **Cloudflare Tunnel** – Zero-config public exposure
- **PostgreSQL** – Primary database
- **Redis** – Caching and session storage
- **Nginx** – Static file serving
## Quick Start
### Prerequisites
- Docker and Docker Compose
- Node.js (for development)
- Go (for backend development)
- Git
### Installation
### Installation with Docker (Recommended)
1. **Clone and setup:**
1. **Clone the repository**
```bash
git clone <repository-url>
cd Containr
git clone https://github.com/your-username/containr.git
cd containr
```
2. **Configure environment:**
2. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your configuration
```
### Running the Application
3. **Start all services**
```bash
# Development mode with hot reload
./start-unified.sh dev
# Production mode (requires DOMAIN env var)
export DOMAIN=yourdomain.com
./start-unified.sh prod
# Production with Cloudflare tunnel (requires CLOUDFLARED_TOKEN)
export CLOUDFLARED_TOKEN=your_token_here
./start-unified.sh cloudflare
```
**Single Docker Compose File - Multiple Environments**
```bash
# Development mode with hot reload
./start-unified.sh dev
# Production mode (requires DOMAIN env var)
export DOMAIN=yourdomain.com
./start-unified.sh prod
# Production with Cloudflare tunnel (requires CLOUDFLARED_TOKEN)
export CLOUDFLARED_TOKEN=your_token_here
./start-unified.sh cloudflare
# Stop all services
./start-unified.sh stop
# View logs
./start-unified.sh logs
# Check status
./start-unified.sh status
# Clean everything
./start-unified.sh clean
```
### Access Points
**Development:**
- Frontend: http://localhost
- API: http://api.localhost
- Traefik Dashboard: http://localhost:8080
**Production:**
- Frontend: https://your-domain.com
- API: https://api.your-domain.com
- Traefik Dashboard: https://traefik.your-domain.com
**Cloudflare Tunnel:**
- Check your Cloudflare dashboard for tunnel URLs
4. **Access the application**
- **Development**: http://localhost (Frontend), http://api.localhost (API), http://localhost:8080 (Traefik Dashboard)
- **Production**: https://your-domain.com, https://api.your-domain.com, https://traefik.your-domain.com
- **Cloudflare Tunnel**: Check your Cloudflare dashboard for tunnel URLs
### Management Commands
```bash
./start.sh logs # View logs
./start.sh status # Check service status
./start.sh stop # Stop all services
./start.sh clean # Clean up containers and volumes
./start.sh help # Show all commands
./start-unified.sh stop # Stop all services
./start-unified.sh logs # View logs
./start-unified.sh status # Check service status
./start-unified.sh clean # Clean up containers and volumes
./start-unified.sh help # Show all commands
```
## Features
- 🐳 **Container Management** - Deploy and manage containers
- ☁️ **Cloudflare Tunnel** - Zero-config deployment with automatic SSL
- 🌐 **Web Interface** - Modern React-based UI
- 🔧 **Settings Panel** - Visual configuration management
- 📊 **Infrastructure Monitoring** - Real-time resource monitoring
- 🔐 **Security** - Built-in authentication and authorization
## Cloudflare Setup
1. **Create a tunnel** in your [Cloudflare Dashboard](https://dash.cloudflare.com/argotunnel)
2. **Copy the tunnel token**
3. **Add to .env:**
```env
CLOUDFLARED_TOKEN=your_tunnel_token_here
```
4. **Start with tunnel:**
```bash
./start.sh cloudflare
```
## Development
### Frontend Development
### Project Structure
```
containr/
├── cmd/ # Application entry points
│ ├── server/ # Main server application
│ └── cli/ # CLI tool
├── internal/ # Private application code
│ ├── api/ # HTTP handlers
│ ├── config/ # Configuration
│ ├── database/ # Database operations
│ ├── docker/ # Docker integration
│ ├── middleware/ # HTTP middleware
│ ├── security/ # Security features
│ └── ... # Other internal packages
├── src/ # Frontend React application
├── docs/ # Documentation
├── migrations/ # Database migrations
├── docker-compose.yml # Multi-service orchestration
├── Dockerfile.backend # Backend Docker image
├── Dockerfile.frontend # Frontend Docker image
├── start-unified.sh # Startup script
└── README.md
```
### Local Development
```bash
cd frontend
# Backend
go mod download
go run cmd/server/main.go
# Frontend
npm install
npm run dev
```
### Backend Development
```bash
cd backend
go mod download
go run main.go
```
## Documentation
Comprehensive documentation is available in the project:
- **[Cloudflare Setup](./CLOUDFLARE_SETUP.md)** – Cloudflare tunnel configuration
- **[Docker Setup](./DOCKER_SETUP.md)** – Docker deployment guide
- **[Autoscaling](./AUTOSCALING.md)** – Auto-scaling configuration
- **[Dashboard Guide](./dashboard.md)** – Dashboard usage guide
- **[API Documentation](./docs/api/openapi.yaml)** – REST API reference
## Configuration
@@ -121,38 +227,100 @@ go run main.go
Key configuration options in `.env`:
```env
```bash
# Domain Configuration (optional if using Cloudflare)
DOMAIN=yourdomain.com
ACME_EMAIL=admin@yourdomain.com
# Database
# Database Configuration
POSTGRES_DB=containr
POSTGRES_USER=containr_user
POSTGRES_PASSWORD=secure_password
POSTGRES_PASSWORD=your_secure_postgres_password
# Redis Configuration
REDIS_PASSWORD=your_secure_redis_password
# Application Configuration
JWT_SECRET=your_very_secure_jwt_secret_key_here
CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
# Traefik Authentication (Basic Auth for dashboard)
TRAEFIK_AUTH=admin:$apr1$b8mh8c8v$KkR8hQZQZQZQZQZQZQZQZ/
# Cloudflare Tunnel (alternative to domain)
CLOUDFLARED_TOKEN=your_tunnel_token_here
CLOUDFLARED_TOKEN=your_cloudflare_tunnel_token_here
# Application
JWT_SECRET=your_jwt_secret
CORS_ALLOWED_ORIGINS=https://yourdomain.com
# Optional: Custom Docker Registry
DOCKER_REGISTRY=your-registry.com
DOCKER_USERNAME=your_username
DOCKER_PASSWORD=your_password
# Optional: External Services
SENTRY_DSN=https://your-sentry-dsn
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url
# Development/Testing
ENVIRONMENT=development
DEBUG=true
```
## Architecture
- **Frontend**: React + TypeScript + Vite + TailwindCSS
- **Backend**: Go + Gin + PostgreSQL + Redis
- **Proxy**: Traefik with automatic SSL
- **Tunnel**: Cloudflare Argo Tunnel (optional)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
Building Containr as a solo developer has been an incredible journey, but it's always better when we build together! Whether you're fixing a typo, adding a feature, or just sharing ideas – your contribution matters.
**Feel free to contribute and enhance it to your liking. Help me make this project successful!**
Every contribution, no matter how small, helps turn this solo dream into a community success story. Whether you're a seasoned developer or just starting out, your perspective and skills can help make Containr better for everyone.
Here's how you can join this adventure:
1. **Fork the repository** and make it your own
2. **Create a 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** – I'll be excited to review it!
### Development Guidelines
- Follow Go coding standards for backend development
- Use TypeScript for frontend development
- Write tests for new features (helps future you!)
- Update documentation as needed
- Remember: this is a labor of love, so let's keep it fun and welcoming
Don't hesitate to reach out if you're new to contributing – we all started somewhere, and I'm happy to help you get started!
## License
MIT License - see LICENSE file for details
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Community & Support
- **Issues**: Use GitHub Issues for bug reports and feature requests
- **Discussions**: Use GitHub Discussions for questions and community support
- **Documentation**: Check the project files for comprehensive guides
## Acknowledgements
### Inspiration
- **[Portainer](https://www.portainer.io/)** – Container management UI inspiration
- **[Docker Compose](https://docs.docker.com/compose/)** – Service orchestration concepts
- **[Traefik](https://traefik.io/)** – Reverse proxy and load balancing
- **[Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/)** – Zero-config deployment
### Technology Stack
This project is built with amazing open-source technologies:
- **Frontend**: React, TypeScript, Vite, TailwindCSS
- **Backend**: Go, Gin, GORM, PostgreSQL
- **Infrastructure**: Docker, Traefik, Cloudflare, Redis
## A Personal Note
Thank you for taking the time to look at my project. Containr represents months of learning, building, and dreaming – all in the service of creating something that makes container management a little more accessible and a lot more powerful.
In a world of complex orchestration tools and expensive cloud services, I believe there's beauty in owning your infrastructure. Containr is my attempt to build that bridge between simplicity and power.
Whether you use it, contribute to it, or just find inspiration here – know that you're part of something special. A solo developer's dream, powered by AI assistance, and shared with the open-source community.
---
**Containr** – Built with ❤️ by one human, one AI, and a passion for better container management.