Skip to content

Commit 1d1b6ab

Browse files
cyclotruccyclotruc
committed
better readme
1 parent df475a6 commit 1d1b6ab

File tree

1 file changed

+276
-2
lines changed

1 file changed

+276
-2
lines changed

‎README.md‎

Lines changed: 276 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,276 @@
1-
# gitcontainer
2-
Turn any git repo into a container, made in OpenAI hackaton
1+
# Gitcontainer 🐳
2+
3+
**Turn any GitHub repository into a production-ready Docker container with AI-powered Dockerfile generation.**
4+
5+
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
6+
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
7+
[![FastAPI](https://img.shields.io/badge/FastAPI-0.68+-00a393.svg)](https://fastapi.tiangolo.com/)
8+
9+
Gitcontainer is an AI-powered web application that automatically generates production-ready Dockerfiles by analyzing GitHub repositories. Simply paste a GitHub URL and get a tailored Dockerfile with intelligent base image selection, dependency management, and Docker best practices.
10+
11+
## ✨ Features
12+
13+
- **🤖 AI-Powered Analysis**: Uses OpenAI GPT-4 to analyze repository structure and generate intelligent Dockerfiles
14+
- **⚡ Real-time Streaming**: Watch the AI generate your Dockerfile in real-time with WebSocket streaming
15+
- **🎯 Smart Detection**: Automatically detects technology stacks (Python, Node.js, Java, Go, etc.)
16+
- **🔧 Production-Ready**: Generates Dockerfiles following best practices with proper security, multi-stage builds, and optimization
17+
- **📋 Additional Instructions**: Add custom requirements for specialized environments
18+
- **📄 Docker Compose**: Automatically suggests docker-compose.yml for complex applications
19+
- **🎨 Modern UI**: Clean, responsive interface with Monaco editor for syntax highlighting
20+
- **📱 Mobile Friendly**: Works seamlessly on desktop and mobile devices
21+
22+
## 🚀 Quick Start
23+
24+
### Prerequisites
25+
26+
- Python 3.9 or higher
27+
- Git
28+
- OpenAI API key
29+
30+
### Installation
31+
32+
1. **Clone the repository:**
33+
```bash
34+
git clone https://github.com/cyclotruc/gitcontainer.git
35+
cd gitcontainer
36+
```
37+
38+
2. **Install dependencies:**
39+
```bash
40+
pip install -r requirements.txt
41+
```
42+
43+
3. **Set up environment variables:**
44+
```bash
45+
# Create .env file
46+
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
47+
```
48+
49+
4. **Run the application:**
50+
```bash
51+
python app.py
52+
```
53+
54+
5. **Open your browser:**
55+
Navigate to `http://localhost:8000`
56+
57+
## 🐳 Docker Deployment
58+
59+
### Build and run with Docker:
60+
61+
```bash
62+
# Build the image
63+
docker build -t gitcontainer .
64+
65+
# Run the container
66+
docker run -p 8000:8000 -e OPENAI_API_KEY=your_api_key gitcontainer
67+
```
68+
69+
### Using docker-compose:
70+
71+
```yaml
72+
version: '3.8'
73+
services:
74+
gitcontainer:
75+
build: .
76+
ports:
77+
- "8000:8000"
78+
environment:
79+
- OPENAI_API_KEY=your_openai_api_key_here
80+
volumes:
81+
- ./repos:/app/repos # Persist cloned repositories
82+
```
83+
84+
## 🛠️ How It Works
85+
86+
1. **Repository Cloning**: Gitcontainer clones the GitHub repository locally using Git
87+
2. **Code Analysis**: Uses [gitingest](https://github.com/cyclotruc/gitingest) to analyze the repository structure and extract relevant information
88+
3. **AI Generation**: Sends the analysis to OpenAI GPT-4 with specialized prompts for Dockerfile generation
89+
4. **Smart Optimization**: The AI considers:
90+
- Technology stack detection
91+
- Dependency management
92+
- Security best practices
93+
- Multi-stage builds when beneficial
94+
- Port configuration
95+
- Environment variables
96+
- Health checks
97+
98+
## 📁 Project Structure
99+
100+
```
101+
cyclotruc-gitcontainer/
102+
├── app.py # Main FastAPI application
103+
├── requirements.txt # Python dependencies
104+
├── .env # Environment variables (create this)
105+
├── static/ # Static assets (icons, CSS)
106+
├── templates/
107+
│ └── index.jinja # Main HTML template
108+
└── tools/ # Core functionality modules
109+
├── __init__.py
110+
├── create_container.py # AI Dockerfile generation
111+
├── git_operations.py # GitHub repository cloning
112+
└── gitingest.py # Repository analysis
113+
```
114+
115+
## 🔧 API Reference
116+
117+
### WebSocket Streaming
118+
119+
Connect to `/ws/{session_id}` for real-time generation updates:
120+
121+
```javascript
122+
const ws = new WebSocket('ws://localhost:8000/ws/session_123');
123+
ws.onmessage = (event) => {
124+
const data = JSON.parse(event.data);
125+
console.log(data.type, data.content);
126+
};
127+
```
128+
129+
### Health Check
130+
131+
```bash
132+
curl http://localhost:8000/health
133+
```
134+
135+
## 🎛️ Configuration
136+
137+
### Environment Variables
138+
139+
| Variable | Description | Required |
140+
|----------|-------------|----------|
141+
| `OPENAI_API_KEY` | Your OpenAI API key | Yes |
142+
| `PORT` | Server port (default: 8000) | No |
143+
| `HOST` | Server host (default: 0.0.0.0) | No |
144+
145+
### Advanced Usage
146+
147+
You can use the tools programmatically:
148+
149+
```python
150+
from tools import clone_repo_tool, gitingest_tool, create_container_tool
151+
import asyncio
152+
153+
async def generate_dockerfile(github_url):
154+
# Clone repository
155+
clone_result = await clone_repo_tool(github_url)
156+
157+
# Analyze with gitingest
158+
analysis = await gitingest_tool(clone_result['local_path'])
159+
160+
# Generate Dockerfile
161+
dockerfile = await create_container_tool(
162+
gitingest_summary=analysis['summary'],
163+
gitingest_tree=analysis['tree'],
164+
gitingest_content=analysis['content']
165+
)
166+
167+
return dockerfile
168+
169+
# Usage
170+
result = asyncio.run(generate_dockerfile("https://github.com/user/repo"))
171+
print(result['dockerfile'])
172+
```
173+
174+
## 🤝 Contributing
175+
176+
We welcome contributions! Here's how to get started:
177+
178+
1. Fork the repository
179+
2. Create a feature branch: `git checkout -b feature-name`
180+
3. Make your changes and test them
181+
4. Commit with clear messages: `git commit -m "Add feature X"`
182+
5. Push to your fork: `git push origin feature-name`
183+
6. Open a Pull Request
184+
185+
### Development Setup
186+
187+
```bash
188+
# Install development dependencies
189+
pip install -r requirements.txt
190+
191+
# Run with auto-reload
192+
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
193+
```
194+
195+
## 🧪 Testing
196+
197+
Test with example repositories:
198+
199+
- **Simple Python app**: `https://github.com/cyclotruc/gitingest`
200+
- **This project**: `https://github.com/cyclotruc/gitcontainer`
201+
- **Complex Node.js app**: Any Express.js repository
202+
- **Multi-service app**: Repositories with multiple services
203+
204+
## 🎨 Customization
205+
206+
### Adding Custom Instructions
207+
208+
Use the "Additional instructions" feature to customize generation:
209+
210+
- `"Use Alpine Linux for smaller image size"`
211+
- `"Include Redis and PostgreSQL"`
212+
- `"Optimize for production deployment"`
213+
- `"Add development tools for debugging"`
214+
215+
### Extending Technology Support
216+
217+
Add new technology detection in `tools/create_container.py`:
218+
219+
```python
220+
# Add your technology patterns to the AI prompt
221+
technology_patterns = {
222+
"rust": ["Cargo.toml", "src/main.rs"],
223+
"ruby": ["Gemfile", "app.rb", "config.ru"],
224+
# Add more...
225+
}
226+
```
227+
228+
## 🐛 Troubleshooting
229+
230+
### Common Issues
231+
232+
**"OPENAI_API_KEY not found"**
233+
- Ensure your `.env` file contains the API key
234+
- Check that the environment variable is properly set
235+
236+
**"Failed to clone repository"**
237+
- Verify the GitHub URL is correct and public
238+
- Check your internet connection
239+
- Ensure Git is installed on your system
240+
241+
**"Generation timeout"**
242+
- Large repositories may take longer to process
243+
- Check your OpenAI API quota and limits
244+
245+
**Monaco Editor not loading**
246+
- Ensure you have internet connection for CDN resources
247+
- Check browser console for JavaScript errors
248+
249+
### Performance Tips
250+
251+
- **Large repositories**: Consider adding `.gitignore` patterns to exclude large files
252+
- **Private repositories**: Currently only public GitHub repositories are supported
253+
- **API limits**: Monitor your OpenAI API usage to avoid rate limits
254+
255+
## 📝 License
256+
257+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
258+
259+
## 🙏 Acknowledgments
260+
261+
- **[OpenAI](https://openai.com/)** for providing the GPT-4 API
262+
- **[gitingest](https://github.com/cyclotruc/gitingest)** for repository analysis capabilities
263+
- **[FastAPI](https://fastapi.tiangolo.com/)** for the excellent web framework
264+
- **[Monaco Editor](https://microsoft.github.io/monaco-editor/)** for code syntax highlighting
265+
266+
## 🔗 Links
267+
268+
- **GitHub Repository**: [https://github.com/cyclotruc/gitcontainer](https://github.com/cyclotruc/gitcontainer)
269+
- **Demo**: Try it live with example repositories
270+
- **Issues**: [Report bugs or request features](https://github.com/cyclotruc/gitcontainer/issues)
271+
272+
---
273+
274+
**Made with ❤️ by [Romain Courtois](https://github.com/cyclotruc)**
275+
276+
*Turn any repository into a container in seconds!*

0 commit comments

Comments
 (0)