> ## Documentation Index
> Fetch the complete documentation index at: https://wukong.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Node Deployment

> Deploy WuKongIM single node instance in Kubernetes cluster using Helm

Deploy WuKongIM single node instance in Kubernetes cluster, suitable for development, testing, and small-scale production environments.

## Deployment Features

**Advantages**:

* High availability and strong disaster recovery capability
* Supports online scaling
* Real-time automatic backup between multiple replicas
* Load balancing without manual configuration
* Fast scaling

**Applicable scenarios**:

* Applications with high data security requirements
* Large applications
* Environments requiring rapid deployment

<Warning>
  **Note**: WuKongIM currently supports hot scaling but does not support hot shrinking!
</Warning>

## Prerequisites

* Kubernetes cluster 1.19+
* kubectl configured and able to access cluster
* Helm 3.0+
* At least 2GB available memory and 2 CPU cores

## Deployment Steps

### 1. Add Helm Repository

```bash theme={null}
helm repo add wukongim https://wukongim.github.io/helm/
```

### 2. Update Helm Repository

```bash theme={null}
helm repo update
```

### 3. Search Available Charts

```bash theme={null}
helm search repo wukongim
```

### 4. Deploy WuKongIM

```bash theme={null}
# Single node deployment (replica count is 1)
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=1
```

**Optional parameters**:

* `replicaCount=1`: Number of replicas (default is 2)
* `externalIP=<IP_ADDRESS>`: External IP address

### 5. Check Installation Status

```bash theme={null}
helm status wkim -n wukongim
```

### 6. Verify Deployment

```bash theme={null}
# Check Pod status
kubectl get pods -n wukongim

# Check service status
kubectl get svc -n wukongim

# View logs
kubectl logs -l app.kubernetes.io/name=wukongim -n wukongim
```

## Access Services

### Port Forward Access

```bash theme={null}
# API service
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim

# WebSocket service
kubectl port-forward svc/wkim-wukongim 5200:5200 -n wukongim

# Demo interface
kubectl port-forward svc/wkim-wukongim 5172:5172 -n wukongim

# Management interface
kubectl port-forward svc/wkim-wukongim 5300:5300 -n wukongim
```

### Access URLs

* **API Endpoint**: [http://localhost:5001](http://localhost:5001)
* **WebSocket**: ws\://localhost:5200
* **Demo Interface**: [http://localhost:5172](http://localhost:5172)
* **Management Interface**: [http://localhost:5300](http://localhost:5300)

## Configuration Options

### Common Helm Parameters

```bash theme={null}
# Complete configuration example
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=1 \
  --set image.tag=v2.0.0 \
  --set service.type=LoadBalancer \
  --set persistence.enabled=true \
  --set persistence.size=20Gi \
  --set resources.requests.memory=2Gi \
  --set resources.requests.cpu=1000m
```

### Main Configuration Parameters

| Parameter             | Description               | Default Value |
| --------------------- | ------------------------- | ------------- |
| `replicaCount`        | Number of replicas        | `2`           |
| `image.tag`           | Image version             | `latest`      |
| `service.type`        | Service type              | `ClusterIP`   |
| `persistence.enabled` | Enable persistent storage | `true`        |
| `persistence.size`    | Storage size              | `10Gi`        |
| `externalIP`          | External IP address       | `""`          |

## Scaling Operations

### Scale to Multi-Node

```bash theme={null}
# Scale to 3 replicas
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version 0.1.0 \
  --set replicaCount=3
```

### Verify Scaling

```bash theme={null}
# Check Pod count
kubectl get pods -n wukongim

# Check cluster status
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/cluster/nodes
```

## Troubleshooting

### Common Issues

**Pod startup failure**:

```bash theme={null}
# Check Pod status
kubectl get pods -n wukongim

# View detailed information
kubectl describe pod <pod-name> -n wukongim

# View logs
kubectl logs <pod-name> -n wukongim
```

**Service inaccessible**:

```bash theme={null}
# Check service status
kubectl get svc -n wukongim

# Check endpoints
kubectl get endpoints -n wukongim

# Test service connectivity
kubectl exec -it <pod-name> -n wukongim -- wget -qO- http://localhost:5001/health
```

**Storage issues**:

```bash theme={null}
# Check PVC status
kubectl get pvc -n wukongim

# View storage details
kubectl describe pvc <pvc-name> -n wukongim
```

### Log Viewing

```bash theme={null}
# View real-time logs
kubectl logs -f deployment/wkim-wukongim -n wukongim

# View all replica logs
kubectl logs -l app.kubernetes.io/name=wukongim -n wukongim

# View historical logs
kubectl logs deployment/wkim-wukongim -n wukongim --previous
```

## Upgrade and Maintenance

### Version Upgrade

```bash theme={null}
# Update Helm repository
helm repo update

# Search for new versions
helm search repo wukongim

# Upgrade to new version
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <new_version>
```

### Data Backup

```bash theme={null}
# Create data snapshot
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  tar czf /tmp/backup-$(date +%Y%m%d).tar.gz /data

# Copy backup file to local
kubectl cp wukongim/<pod-name>:/tmp/backup-$(date +%Y%m%d).tar.gz \
  ./wukongim-backup-$(date +%Y%m%d).tar.gz
```

## Uninstall

```bash theme={null}
# Uninstall WuKongIM
helm uninstall wkim -n wukongim

# Delete namespace (optional)
kubectl delete namespace wukongim
```

## Advanced Configuration

### Custom Values File

Create a `values.yaml` file for custom configuration:

```yaml theme={null}
# values.yaml
replicaCount: 1

image:
  repository: registry.cn-shanghai.aliyuncs.com/wukongim/wukongim
  tag: "v2"
  pullPolicy: IfNotPresent

service:
  type: LoadBalancer
  ports:
    api: 5001
    tcp: 5100
    websocket: 5200
    management: 5300
    demo: 5172

persistence:
  enabled: true
  size: 20Gi
  storageClass: ""

resources:
  requests:
    memory: "2Gi"
    cpu: "1000m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

nodeSelector: {}
tolerations: []
affinity: {}
```

Deploy with custom values:

```bash theme={null}
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  -f values.yaml
```

### Environment Variables

Configure WuKongIM through environment variables:

```yaml theme={null}
# In values.yaml
env:
  - name: WK_MODE
    value: "release"
  - name: WK_TOKENAUTHON
    value: "true"
  - name: WK_EXTERNAL_IP
    value: "your-external-ip"
```

## Monitoring and Observability

### Enable Monitoring

```bash theme={null}
# Deploy with monitoring enabled
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --set monitoring.enabled=true \
  --set monitoring.prometheus.enabled=true
```

### Health Checks

```bash theme={null}
# Check health endpoint
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  curl -f http://localhost:5001/health

# Check cluster status
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  curl -f http://localhost:5001/cluster/nodes
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Node Deployment" icon="server" href="/en/installation/k8s/multi-node">
    Deploy high availability cluster
  </Card>

  <Card title="Server Configuration" icon="gear" href="/en/server/configuration">
    Detailed configuration options
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/en/installation/docker/single-node">
    Docker deployment method
  </Card>

  <Card title="API Documentation" icon="code" href="/en/api/introduction">
    Start using the API
  </Card>
</CardGroup>