neon-vortex/README.md

# Neon Vortex - Docker & Kubernetes Deployment

This repository contains the Neon Vortex web application with Docker and Kubernetes deployment configurations.

## Directory Structure

```
.
├── htlm/                          # Application files
│   ├── Neon Vortex.html          # Main application
│   ├── Neon Vortex.js            # JavaScript bundle
│   ├── Neon Vortex.wasm          # WebAssembly binary
│   ├── Dockerfile                 # Multi-arch Docker configuration
│   ├── nginx.conf                 # Nginx server configuration
│   └── ...                        # Other assets
├── neon-vortex-chart/            # Helm chart
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
└── build-and-push.sh             # Build script for multi-arch images
```

## Prerequisites

- Docker with BuildKit enabled
- Access to Harbor registry at `images.caffeinetux.com`
- kubectl configured for your k3s cluster
- Helm 3.x installed

## Building and Pushing the Docker Image

The application supports multiple architectures: `linux/amd64`, `linux/arm64`, and `linux/arm/v7`.

### Build and Push

```bash
# Build and push with 'latest' tag
./build-and-push.sh

# Build and push with custom tag
./build-and-push.sh v1.0.0
```

### Manual Build (without script)

```bash
# Create buildx builder (first time only)
docker buildx create --name multiarch-builder --use
docker buildx inspect --bootstrap

# Build and push
cd htlm
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --tag images.caffeinetux.com/apps/neon-vortex:latest \
  --push \
  .
```

## Deploying to Kubernetes

### Quick Deploy

```bash
# Install with default values
helm install neon-vortex ./neon-vortex-chart

# Install in specific namespace
helm install neon-vortex ./neon-vortex-chart -n neon-vortex --create-namespace
```

### Custom Configuration

Create a `custom-values.yaml` file:

```yaml
# Example custom values
replicaCount: 3

image:
  tag: "v1.0.0"

service:
  type: NodePort
  nodePort: 30080

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: neon-vortex.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: neon-vortex-tls
      hosts:
        - neon-vortex.example.com

resources:
  limits:
    cpu: 500m
    memory: 256Mi
  requests:
    cpu: 200m
    memory: 128Mi
```

Deploy with custom values:

```bash
helm install neon-vortex ./neon-vortex-chart -f custom-values.yaml
```

### Harbor Authentication

If your Harbor registry requires authentication, create a secret:

```bash
kubectl create secret docker-registry harbor-registry-secret \
  --docker-server=images.caffeinetux.com \
  --docker-username=YOUR_USERNAME \
  --docker-password=YOUR_PASSWORD \
  --docker-email=YOUR_EMAIL
```

Then update `values.yaml`:

```yaml
imagePullSecrets:
  - name: harbor-registry-secret
```

## Accessing the Application

### ClusterIP (default)

```bash
# Port forward to local machine
kubectl port-forward svc/neon-vortex 8080:80

# Access at http://localhost:8080
```

### NodePort

```bash
# Get the NodePort
kubectl get svc neon-vortex

# Access at http://<NODE_IP>:<NODE_PORT>
```

### Ingress

Access at the configured hostname (e.g., `http://neon-vortex.example.com`)

## Helm Chart Configuration

### Key Values

| Parameter | Description | Default |
|-----------|-------------|---------|
| `replicaCount` | Number of replicas | `2` |
| `image.registry` | Harbor registry URL | `images.caffeinetux.com` |
| `image.repository` | Image repository path | `apps/neon-vortex` |
| `image.tag` | Image tag | `latest` |
| `service.type` | Service type | `ClusterIP` |
| `service.port` | Service port | `80` |
| `service.targetPort` | Container port | `8080` |
| `ingress.enabled` | Enable ingress | `false` |
| `autoscaling.enabled` | Enable HPA | `false` |
| `resources.limits.cpu` | CPU limit | `200m` |
| `resources.limits.memory` | Memory limit | `128Mi` |

### Security Features

- Non-root user (nginx:101)
- Read-only root filesystem option
- Security context with dropped capabilities
- Pod security context
- Resource limits

## Upgrading

```bash
# Upgrade to new version
helm upgrade neon-vortex ./neon-vortex-chart

# Upgrade with new image tag
helm upgrade neon-vortex ./neon-vortex-chart --set image.tag=v1.0.1
```

## Uninstalling

```bash
# Uninstall the release
helm uninstall neon-vortex

# Uninstall from specific namespace
helm uninstall neon-vortex -n neon-vortex
```

## Troubleshooting

### Check pod status

```bash
kubectl get pods -l app.kubernetes.io/name=neon-vortex
```

### View logs

```bash
kubectl logs -l app.kubernetes.io/name=neon-vortex
```

### Describe pod

```bash
kubectl describe pod -l app.kubernetes.io/name=neon-vortex
```

### Test connectivity

```bash
kubectl run -it --rm debug --image=alpine --restart=Never -- sh
# Inside the pod:
wget -O- http://neon-vortex
```

## Application Features

- Static web application served via nginx
- WebAssembly support
- Service worker for offline capability
- Gzip compression
- Proper MIME types for all assets
- Security headers (X-Frame-Options, CSP, etc.)
- Health checks

## License

Configure according to your application's license.