Maison/arti-api/README.md

# Arti-Api

This is the api part of artifactory server.

Artifactory server consist in backends servers providing services to applications: 
- **docker** : a docker registry
- **helm** : chart museum
- **debian** : Nginx serving .deb files for arm64 and amd64 binaries

Each server are in a pod, sharing a pvc volume, with following folder structure :

```console
.
├── docker
├── debian
|   ├── dist
|   |   ├── Release            
|   |   └── main
|   |       ├── binary-arm64
|   |       └── binary-amd64  
|   └── pool
└── charts
```

## Api 

The api pod, must be able to update shared pvc volume :
- add / update / delete binary
- refresh what is needed

## Container Application

This repository now contains a complete containerized FastAPI application that provides REST endpoints to manage the artifactory server components.

### Features

- **Debian Package Management**: Upload, delete, and list `.deb` packages
- **Helm Chart Management**: Upload, delete, and list Helm charts (`.tgz` files)
- **Docker Registry Integration**: List Docker images in the registry
- **User Management**: Create, update, delete, and list Docker registry users with htpasswd authentication
- **Repository Refresh**: Refresh package indexes and chart repositories
- **Health Monitoring**: Health check endpoints for container orchestration

### API Endpoints

#### Health & Status
- `GET /` - Root endpoint with API status
- `GET /health` - Health check endpoint

#### Debian Repository
- `POST /debian/upload` - Upload .deb packages
- `GET /debian/packages` - List all Debian packages
- `DELETE /debian/package/{package_name}` - Delete a specific package
- `POST /refresh/debian` - Refresh Debian package indexes

#### Helm Repository
- `POST /helm/upload` - Upload Helm charts (.tgz files)
- `GET /helm/charts` - List all Helm charts
- `DELETE /helm/chart/{chart_name}` - Delete a specific chart
- `POST /refresh/helm` - Refresh Helm chart index

#### Docker Registry
- `GET /docker/images` - List Docker images

#### User Management
- `GET /users` - List all Docker registry users
- `GET /users/{username}` - Get user information
- `POST /users` - Create or update a user
- `DELETE /users/{username}` - Delete a user

#### General Operations
- `POST /refresh/all` - Refresh all repositories

### Quick Start

#### Using Docker Compose (Recommended for development)
```bash
# Build and run the container
./build.sh
docker-compose up -d

# Access the API
curl http://localhost:8000/health
```

#### Using Kubernetes (Recommended for production)
```bash
# Build the container
./build.sh

# Deploy to Kubernetes
kubectl apply -f kubernetes.yaml

# Check deployment status
kubectl get pods -l app=arti-api
```

#### Manual Docker Build
```bash
# Build the image
docker build -t arti-api:latest .

# Run the container
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/data:/data \
  --name arti-api \
  arti-api:latest
```

### Configuration

The application expects the shared PVC volume to be mounted at `/data` with the following structure:
- `/data/docker` - Docker registry data
- `/data/debian/dist` - Debian distribution metadata
- `/data/debian/pool` - Debian package pool
- `/data/charts` - Helm charts storage
- `/data/htpasswd` - Docker registry user authentication file

### Environment Variables

- `PYTHONUNBUFFERED=1` - Ensures real-time logging output

### API Documentation

Once the container is running, you can access comprehensive API documentation:

#### Interactive Documentation
- **Swagger UI**: `http://localhost:8000/docs` - Interactive API testing interface
- **ReDoc**: `http://localhost:8000/redoc` - Clean, responsive API documentation
- **OpenAPI Schema**: `http://localhost:8000/openapi.json` - Machine-readable API specification

#### Quick Documentation Server
```bash
# Start documentation server with one command
./serve-docs.sh

# Or manually
docker run -d -p 8000:8000 --name arti-api-docs arti-api:latest
```

#### API Features in Documentation
- 📋 **Comprehensive endpoint documentation** with detailed descriptions
- 🔧 **Interactive testing interface** - test endpoints directly from the browser
- 📝 **Request/response examples** with real data samples
- 🏷️ **Organized by tags** - endpoints grouped by functionality (health, debian, helm, docker, refresh)
- 📊 **Schema definitions** for all data models
- ⚠️ **Error response documentation** with HTTP status codes
- 🚀 **Example curl commands** for all endpoints

#### Testing Examples
See `API_EXAMPLES.md` for comprehensive testing examples including:
- Curl commands for all endpoints
- Python code examples
- Expected response formats
- Error handling examples

### File Structure

```
.
├── app.py                    # Main FastAPI application with comprehensive Swagger docs
├── requirements.txt          # Python dependencies
├── Dockerfile               # Container definition
├── docker-compose.yaml      # Simple Docker Compose configuration
├── docker-compose-full.yaml # Complete artifactory stack with authentication
├── kubernetes.yaml          # Kubernetes deployment manifests
├── build.sh                 # Build script
├── serve-docs.sh            # Documentation server script
├── setup-full-stack.sh      # Complete artifactory setup with authentication
├── API_EXAMPLES.md          # Comprehensive API testing examples
├── CHARTMUSEUM_AUTH.md      # Chart Museum authentication guide
├── .dockerignore            # Docker ignore file
└── README.md                # This file
```

## Chart Museum Authentication

Yes! Chart Museum can be protected with the same htpasswd file managed by the Arti-API. See `CHARTMUSEUM_AUTH.md` for complete configuration details.

### Quick Setup with Authentication

```bash
# Setup complete authenticated artifactory stack
./setup-full-stack.sh

# This creates:
# - Arti-API (port 8000)
# - Chart Museum with htpasswd auth (port 8080)  
# - Docker Registry with htpasswd auth (port 5000)
# - Default users: admin, developer, readonly
```

### Chart Museum Configuration

Chart Museum supports htpasswd authentication using these environment variables:
```bash
HTPASSWD_PATH=/data/htpasswd
AUTH_ANONYMOUS_GET=false
AUTH_REALM="Chart Museum"
```

### Usage Examples

```bash
# Test authenticated access
curl -u admin:admin123 http://localhost:8080/api/charts

# Add authenticated Helm repository
helm repo add myrepo http://admin:admin123@localhost:8080

# Upload chart with authentication
curl -u admin:admin123 --data-binary "@chart.tgz" http://localhost:8080/api/charts
```