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

# 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:

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:

   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

curl http://your-service:4321/

Docker Health Check

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

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

Next.js Project

# 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

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

---

Integration with CI/CD

GitHub Actions Example

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