# Container.mom Operator

A Kubernetes operator for managing containerized applications with automated scaling, DNS management, and usage-based billing.

## Container Images

Container images for all services are automatically built and published to GitHub Container Registry (ghcr.io) when:

- Pushing to the main branch
- Creating a new release tag (v\*)
- Opening a pull request (PR builds are not published)

Images are tagged with:

- Git SHA (e.g. sha-a1b2c3d...)
- Branch name (e.g. main)
- Semantic version for release tags (e.g. v1.0.0, v1.0, v1)

Available images:

- ghcr.io/OWNER/container-mom-web-portal
- ghcr.io/OWNER/container-mom-api-controller
- ghcr.io/OWNER/container-mom-billing-service
- ghcr.io/OWNER/container-mom-metrics-service
- ghcr.io/OWNER/container-mom-dns-manager

Note: Replace OWNER with your GitHub username or organization name.

## Architecture

The operator has been split into multiple services for better scalability and maintainability:

### Core Services

- **Web Portal**: Customer-facing web interface for managing deployments
- **API Controller**: Kubernetes operator for container lifecycle management
- **Metrics Service**: Prometheus-compatible metrics collection and monitoring
- **DNS Manager**: Automated DNS provisioning and management
- **Billing Service**: Usage tracking and payment processing
- **PostgreSQL**: Shared database for persistent storage

### Directory Structure

```
.
├── api/                  # API definitions and schemas
├── bin/                  # Compiled binaries
├── cmd/                  # Command-line tools
├── config/               # Kubernetes configurations
│   ├── manager/          # Operator manager configs
│   ├── manifests/        # Service manifests
│   └── rbac/             # RBAC configurations
├── deploy/
│   ├── base/             # Base Kubernetes manifests
│   └── overlays/         # Environment-specific overlays
│       ├── development/
│       └── production/
├── internal/             # Internal packages
├── lib/                  # Shared libraries
├── public/               # Static assets
├── spec/                 # Tests
└── src/
    ├── web-portal/       # Web interface service
    ├── api-controller/   # Kubernetes operator
    ├── metrics-service/  # Metrics collection
    ├── dns-manager/      # DNS management
    └── billing-service/  # Billing and usage tracking
```

## Development

### Prerequisites

- Go >= 1.21
- Podman 4.0 or higher
- Kubernetes cluster (local or remote)
- kubectl configured with cluster access
- operator-sdk
- kustomize
- controller-gen

### Local Development Setup

1. Clone the repository:

```bash
git clone https://github.com/yourusername/container-mom-operator.git
cd container-mom-operator
```

2. Install development dependencies:

```bash
make install-deps
```

3. Generate API types and controllers:

```bash
make generate
```

4. Build the operator:

```bash
make build
```

5. Run the operator locally:

```bash
make run
```

### Database Management

We use golang-migrate for database migrations:

```bash
# Create a new migration
make migration-create name=add_users_table

# Run migrations
make db-migrate

# Rollback migrations
make db-rollback
```

### Running Tests

```bash
# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific test
go test ./pkg/controller/... -v -run TestSpecificFunction
```

### Development Tools

The project uses several Go development tools:

- `golangci-lint` for code linting
- `gofmt` for code formatting
- `controller-gen` for generating CRDs
- `mockgen` for generating mocks

Run quality checks:

```bash
# Format code
make fmt

# Run linter
make lint

# Generate CRDs
make manifests
```

## Deployment

### Development Environment

```bash
# Build and deploy to development
make dev

# Run locally with Podman
make dev-local

# Forward ports for local access
make port-forward

# Stop port forwarding
make stop-forward

# Check status
make status

# Clean up
make clean
```

### Production Environment

```bash
# Build, push images, and deploy to production
make prod

# Generate deployment manifests
make manifests
```

### Security

Run security checks on container configurations:

```bash
make security-check
```

This verifies:

- Services run as non-root user
- Volume permissions are properly restricted
- Container security settings

## Configuration

### Environment Variables

Each service requires specific environment variables. Create a `.env` file based on `.env.example`:

- `DB_HOST`: PostgreSQL host
- `DB_PORT`: PostgreSQL port
- `DB_USER`: Database username
- `DB_PASSWORD`: Database password
- `METRICS_ENABLED`: Enable metrics collection
- `LOG_LEVEL`: Logging verbosity

### Kubernetes Configuration

The operator uses kustomize for environment-specific configurations:

- Development: `deploy/overlays/development/`

  - Lower resource limits
  - Single replicas
  - Debug logging enabled

- Production: `deploy/overlays/production/`
  - Higher resource limits
  - Multiple replicas
  - Production logging
  - TLS enabled

### Local Development with Podman

The project uses Podman for containerization, offering several advantages:

- Daemonless container engine
- Rootless container execution
- Better security with SELinux integration
- Pod support for multi-container applications

Podman commands:

```bash
# List running containers and pods
podman ps
podman pod ps

# View container logs
podman logs <container-name>

# Execute commands in containers
podman exec -it <container-name> /bin/sh

# Clean up
podman pod rm -f container-mom-dev
podman volume prune
```

## Project Structure

```
.
├── api/                  # API definitions and CRDs
│   └── v1alpha1/        # API version
├── bin/                 # Compiled binaries
├── cmd/                 # Command-line entry points
│   └── manager/        # Operator manager
├── config/             # Kubernetes configurations
│   ├── crd/           # Custom Resource Definitions
│   ├── manager/       # Operator manager configs
│   ├── rbac/          # RBAC configurations
│   └── samples/       # Example CR manifests
├── controllers/        # Kubernetes controllers
├── pkg/               # Internal packages
│   ├── billing/       # Billing service logic
│   ├── dns/          # DNS management
│   └── metrics/      # Metrics collection
├── internal/          # Private application code
├── test/             # Integration tests
└── web/              # Web portal
    ├── handlers/     # HTTP handlers
    ├── middleware/   # HTTP middleware
    └── templates/    # HTML templates
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Please ensure your code:
- Passes `golangci-lint`
- Includes unit tests
- Follows Go best practices and idioms
- Has meaningful commit messages

## License

MIT License - see LICENSE file for details