dealplustech/EASYPANEL_SKILL.md

# Easypanel Deployment Skill

**Skill Name:** `easypanel-deploy`  
**Description:** Deploy Astro/Next.js/Vite apps to Easypanel with Docker  
**Version:** 1.0.0  
**Author:** Deal Plus Tech DevOps

---

## Overview

This skill provides a complete deployment workflow for static site generators (Astro, Next.js, Vite) to Easypanel using Docker containers.

---

## Capabilities

- ✅ **Dockerfile Generation** - Optimized multi-stage Dockerfile
- ✅ **Easypanel Configuration** - Pre-configured for Easypanel deployment
- ✅ **Git Integration** - Auto-deploy on push
- ✅ **Environment Setup** - Environment variables and secrets
- ✅ **Domain Configuration** - Custom domain + SSL setup
- ✅ **Health Checks** - Container health monitoring
- ✅ **Resource Optimization** - Recommended resource allocation

---

## Usage

### Prerequisites

1. Easypanel instance (self-hosted or cloud)
2. Git repository with Astro/Next.js/Vite project
3. Docker installed (for local testing)

### Step 1: Prepare Project

```bash
# Navigate to project
cd your-project

# Ensure build script exists
npm run build

# Test production build
npm run preview
```

### Step 2: Add Deployment Files

Create these files in project root:

**Dockerfile:**
```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/public ./public
EXPOSE 4321
CMD ["npm", "run", "preview", "--", "--host", "0.0.0.0", "--port", "4321"]
```

**.dockerignore:**
```
node_modules
dist
*.log
.git
.env
```

### Step 3: Deploy to Easypanel

#### Option A: Git Repository (Recommended)

1. Login to Easypanel
2. **New Service** → **Git Repository**
3. Select repository and branch
4. Configure:
   - **Build Command:** `npm run build`
   - **Publish Directory:** `dist`
   - **Port:** `4321`
5. Click **Deploy**

#### Option B: Docker Image

1. Build image:
   ```bash
   docker build -t your-app:latest .
   docker push your-registry.com/your-app:latest
   ```

2. Deploy on Easypanel:
   - **New Service** → **Docker Image**
   - Enter image URL
   - Set port: `4321`
   - Click **Deploy**

### Step 4: Configure Domain (Optional)

1. Go to Service Settings → **Domains**
2. Add domain: `your-domain.com`
3. Update DNS:
   ```
   Type: CNAME
   Name: @
   Value: your-service.easypanel.app
   ```
4. Enable SSL

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NODE_ENV` | No | `production` | Node environment |
| `PORT` | No | `4321` | Server port |
| `HOST` | No | `0.0.0.0` | Bind address |

---

## Resource Recommendations

| Project Size | CPU | Memory | Storage |
|--------------|-----|--------|---------|
| **Small** (< 100MB) | 0.5 vCPU | 512MB | 1GB |
| **Medium** (< 500MB) | 1 vCPU | 1GB | 2GB |
| **Large** (> 500MB) | 2 vCPU | 2GB | 5GB |

---

## Health Check

**Endpoint:** `GET /`  
**Expected:** HTTP 200 OK  
**Timeout:** 3 seconds  
**Interval:** 30 seconds

### Manual Health Check

```bash
curl http://your-service:4321/
```

### Docker Health Check

```bash
docker inspect --format='{{.State.Health.Status}}' your-container
```

---

## Troubleshooting

### Build Fails

**Symptoms:** Build command returns error

**Solutions:**
1. Check build logs
2. Verify `package.json` scripts
3. Test locally: `npm run build`
4. Check Node version compatibility

### Container Crashes

**Symptoms:** Container exits immediately

**Solutions:**
1. Check container logs: `docker logs <container>`
2. Verify port configuration
3. Check environment variables
4. Review Dockerfile CMD instruction

### 502 Bad Gateway

**Symptoms:** Service returns 502 error

**Solutions:**
1. Verify container is running
2. Check port mapping
3. Review health check status
4. Inspect application logs

---

## Best Practices

### Security

- ✅ Use `.dockerignore` to exclude sensitive files
- ✅ Run as non-root user (add `USER node` to Dockerfile)
- ✅ Use production dependencies only
- ✅ Enable SSL for custom domains
- ✅ Regular security updates

### Performance

- ✅ Multi-stage Docker builds
- ✅ Minimize Docker image size
- ✅ Enable compression (Easypanel default)
- ✅ Use CDN for static assets
- ✅ Configure proper caching

### Monitoring

- ✅ Enable health checks
- ✅ Monitor resource usage
- ✅ Set up log aggregation
- ✅ Configure alerts for failures
- ✅ Regular backup strategy

---

## Examples

### Astro Project

```bash
# Astro specific configuration
npm create astro@latest
npm run build  # Output: dist/
npm run preview  # Port: 4321
```

### Next.js Project

```bash
# Next.js specific configuration
npx create-next-app
npm run build  # Output: .next/
npm run start  # Port: 3000
```

Update Dockerfile PORT to 3000 for Next.js.

### Vite Project

```bash
# Vite specific configuration
npm create vite@latest
npm run build  # Output: dist/
npx serve dist  # Port: 3000
```

---

## Integration with CI/CD

### GitHub Actions Example

```yaml
name: Deploy to Easypanel

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build Docker Image
        run: docker build -t my-app:latest .
      
      - name: Push to Registry
        run: docker push registry.com/my-app:latest
      
      - name: Deploy to Easypanel
        run: |
          # Use Easypanel API or CLI
          easypanel deploy my-app:latest
```

---

## Resources

- **Easypanel Docs:** https://docs.easypanel.io
- **Docker Docs:** https://docs.docker.com
- **Astro Docs:** https://docs.astro.build
- **Node.js Docker Best Practices:** https://github.com/nodejs/docker-node

---

## Support

For issues or questions:
1. Check troubleshooting section
2. Review Easypanel documentation
3. Check project logs
4. Contact DevOps team

---

**Last Updated:** 2026-03-02  
**Skill Version:** 1.0.0  
**Status:** ✅ Production Ready