TSYSDevStack-SupportStack-Cloudron/Package-Templates/README.md

# Cloudron Package Templates

This directory contains Cloudron packaging templates for common application types.

## Available Templates

### 1. Python Application Template
**File**: `python-app/Dockerfile.template`
**Use Case**: Simple Python web applications (Flask, Django, etc.)
**Dependencies**: System packages, pip requirements

### 2. Go Application Template
**File**: `go-app/Dockerfile.template`
**Use Case**: Go web applications
**Build Pattern**: Multi-stage (builder + runtime)

### 3. Node.js Application Template
**File**: `nodejs-app/Dockerfile.template`
**Use Case**: Node.js web applications
**Build Pattern**: Multi-stage (builder + runtime)

### 4. Django Application Template
**File**: `django-app/`
**Use Case**: Django web applications with PostgreSQL
**Includes**: Dockerfile, start.sh

### 5. Official Image Wrapper Template
**File**: `official-wrapper/Dockerfile.template`
**Use Case**: Applications with existing Docker images
**Build Pattern**: Simple wrapper with start script

### 6. README Template
**File**: `README.template.md`
**Use Case**: All applications
**Includes**: Standard documentation sections

## How to Use Templates

### 1. Copy Template
```bash
# Choose appropriate template
cp -r python-app /path/to/new-package
```

### 2. Customize
```bash
# Edit Dockerfile.template
# Edit CloudronManifest.json.template
# Customize for your application
```

### 3. Build
```bash
# Test build locally
docker build -t myapp:test .
```

## Template Structure

Each template includes:
- **Dockerfile.template**: Docker configuration
- **CloudronManifest.json.template**: Cloudron manifest
- **start.sh.template**: Startup script (if needed)
- **.env.example**: Environment configuration
- **README.template.md**: Documentation template
- **CHANGELOG.template.md**: Changelog template

## Customization Points

### Dockerfile
- Base image selection
- Dependency installation
- Build commands
- Runtime configuration
- Port exposure
- Health checks

### CloudronManifest.json
- Application ID (io.cloudron.appname)
- Title and description
- Ports configuration
- Addons selection
- Memory limits
- Health check paths

### Start Script
- Database wait logic
- Migration commands
- Configuration generation
- Application startup

## Common Patterns

### Database Integration
**PostgreSQL**:
```json
"addons": {
  "postgresql": {
    "version": "14"
  }
}
```

**MySQL**:
```json
"addons": {
  "mysql": {
    "version": "8"
  }
}
```

### Storage
**Localstorage**:
```json
"addons": {
  "localstorage": true
}
```

### Memory Limits
- **Small apps**: 512MB
- **Medium apps**: 1024MB (1GB)
- **Large apps**: 2048MB (2GB)
- **Very large apps**: 4096MB (4GB)

## Best Practices

1. **Use official images** when available
2. **Multi-stage builds** for compiled applications
3. **Wait for dependencies** (database, services)
4. **Health checks** on all services
5. **Environment variable defaults**: `${VAR:-default}`
6. **Make scripts executable** on host, not in Docker RUN
7. **Use .dockerignore** to reduce build context
8. **Document all settings** in .env.example
9. **Test builds locally** before committing
10. **Follow Cloudron conventions** for consistency

## Documentation Reference

For more details on Cloudron packaging patterns:
- See `../JOURNAL.md` for detailed analysis of completed packages
- See `../AGENTS.md` for established patterns and learnings
- See [Cloudron Documentation](https://docs.cloudron.io/packaging/)
- See [Cloudron Repository](https://git.cloudron.io/cloudron/cloudron-apps)

## Support

For questions about templates:
- Refer to `../JOURNAL.md` for detailed examples
- Use patterns from `../AGENTS.md`
- Check completed packages for reference

---

*Templates are based on packages created for TSYSDevStack-SupportStack-Cloudron project.*