📄 production optimizations
This commit is contained in:
RJ
297
ENV_CONFIG_GUIDE.md
Normal file
297
ENV_CONFIG_GUIDE.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# Build-time Environment Variables Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide documents the configuration for build-time environment variables in the Next.js CI/CD pipeline.
|
||||
|
||||
**Problem Solved:** Next.js 16 requires `NEXT_PUBLIC_*` variables available during `npm run build` for:
|
||||
- SEO metadata (`metadataBase`)
|
||||
- Sitemap generation
|
||||
- OpenGraph URLs
|
||||
- RSS feed URLs
|
||||
|
||||
**Solution:** Create `.env` file in CI/CD from Gitea secrets, copy to Docker build context, embed variables in JavaScript bundle.
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
|
||||
### 1. `.gitea/workflows/main.yml`
|
||||
|
||||
**Changes:**
|
||||
- Added step to create `.env` from Gitea secrets (after checkout)
|
||||
- Added cleanup step to remove `.env` after Docker push
|
||||
|
||||
**New Steps:**
|
||||
|
||||
```yaml
|
||||
- name: 📝 Create .env file from Gitea secrets
|
||||
run: |
|
||||
echo "Creating .env file for Docker build..."
|
||||
cat > .env << EOF
|
||||
# Build-time environment variables
|
||||
NEXT_PUBLIC_SITE_URL=${{ secrets.NEXT_PUBLIC_SITE_URL }}
|
||||
NODE_ENV=production
|
||||
NEXT_TELEMETRY_DISABLED=1
|
||||
EOF
|
||||
|
||||
echo "✅ .env file created successfully"
|
||||
echo "Preview (secrets masked):"
|
||||
cat .env | sed 's/=.*/=***MASKED***/g'
|
||||
```
|
||||
|
||||
```yaml
|
||||
- name: 🚀 Push Docker image to registry
|
||||
run: |
|
||||
docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
|
||||
|
||||
# Clean up sensitive files
|
||||
rm -f .env
|
||||
echo "✅ Cleaned up .env file"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. `Dockerfile.nextjs`
|
||||
|
||||
**Changes:**
|
||||
- Added `COPY .env* ./` in builder stage (after copying node_modules, before copying source code)
|
||||
|
||||
**Added Section:**
|
||||
|
||||
```dockerfile
|
||||
# Copy .env file for build-time variables
|
||||
# This file is created by CI/CD workflow from Gitea secrets
|
||||
# NEXT_PUBLIC_* variables are embedded in client-side bundle during build
|
||||
COPY .env* ./
|
||||
```
|
||||
|
||||
**Position:** Between `COPY --from=deps /app/node_modules ./node_modules` and `COPY . .`
|
||||
|
||||
---
|
||||
|
||||
### 3. `.dockerignore`
|
||||
|
||||
**Changes:**
|
||||
- Modified to allow `.env` file (created by CI/CD) while excluding other `.env*` files
|
||||
|
||||
**Updated Section:**
|
||||
|
||||
```
|
||||
# Environment files
|
||||
.env* # Exclude all .env files
|
||||
!.env # EXCEPT .env (needed for build from CI/CD)
|
||||
!.env.example # Keep example
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
- `.env*` excludes all environment files
|
||||
- `!.env` creates exception for main `.env` (from CI/CD)
|
||||
- `.env.local`, `.env.development`, `.env.production.local` remain excluded
|
||||
|
||||
---
|
||||
|
||||
## Gitea Repository Configuration
|
||||
|
||||
### Required Secrets
|
||||
|
||||
Navigate to: **Repository Settings → Secrets**
|
||||
|
||||
Add the following secret:
|
||||
|
||||
| Secret Name | Value | Type | Description |
|
||||
|------------|-------|------|-------------|
|
||||
| `NEXT_PUBLIC_SITE_URL` | `https://yourdomain.com` | Secret or Variable | Production site URL |
|
||||
|
||||
**Notes:**
|
||||
- Can be configured as **Secret** (masked in logs) or **Variable** (visible in logs)
|
||||
- Recommended: Use **Variable** since it's a public URL
|
||||
- For sensitive values (API keys), always use **Secret**
|
||||
|
||||
### Adding Additional Variables
|
||||
|
||||
To add more build-time variables:
|
||||
|
||||
1. **Add to Gitea Secrets/Variables:**
|
||||
```
|
||||
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
|
||||
NEXT_PUBLIC_API_URL=https://api.example.com
|
||||
```
|
||||
|
||||
2. **Update workflow `.env` creation step:**
|
||||
```yaml
|
||||
cat > .env << EOF
|
||||
NEXT_PUBLIC_SITE_URL=${{ secrets.NEXT_PUBLIC_SITE_URL }}
|
||||
NEXT_PUBLIC_GA_ID=${{ secrets.NEXT_PUBLIC_GA_ID }}
|
||||
NEXT_PUBLIC_API_URL=${{ secrets.NEXT_PUBLIC_API_URL }}
|
||||
NODE_ENV=production
|
||||
NEXT_TELEMETRY_DISABLED=1
|
||||
EOF
|
||||
```
|
||||
|
||||
3. **No changes needed to Dockerfile or .dockerignore**
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Local Testing
|
||||
|
||||
1. **Create test `.env` file:**
|
||||
```bash
|
||||
cat > .env << EOF
|
||||
NEXT_PUBLIC_SITE_URL=http://localhost:3030
|
||||
NODE_ENV=production
|
||||
NEXT_TELEMETRY_DISABLED=1
|
||||
EOF
|
||||
```
|
||||
|
||||
2. **Build Docker image:**
|
||||
```bash
|
||||
docker build -t mypage:test -f Dockerfile.nextjs .
|
||||
```
|
||||
|
||||
3. **Verify variable is embedded (should show "NOT FOUND" - correct behavior):**
|
||||
```bash
|
||||
docker run --rm mypage:test node -e "console.log(process.env.NEXT_PUBLIC_SITE_URL || 'NOT FOUND')"
|
||||
```
|
||||
|
||||
**Expected Output:** `NOT FOUND`
|
||||
|
||||
**Why?** `NEXT_PUBLIC_*` variables are embedded in JavaScript bundle during build, NOT available as runtime environment variables.
|
||||
|
||||
4. **Test application starts:**
|
||||
```bash
|
||||
docker run --rm -p 3030:3030 mypage:test
|
||||
```
|
||||
|
||||
Visit `http://localhost:3030` to verify.
|
||||
|
||||
5. **Cleanup:**
|
||||
```bash
|
||||
rm .env
|
||||
docker rmi mypage:test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Pipeline Flow
|
||||
|
||||
### Build Process
|
||||
|
||||
1. **Checkout code** (`actions/checkout@v4`)
|
||||
2. **Create `.env` file** from Gitea secrets
|
||||
3. **Build Docker image:**
|
||||
- Stage 1: Install dependencies
|
||||
- Stage 2: **Copy `.env` → Build Next.js** (variables embedded in bundle)
|
||||
- Stage 3: Production runtime (no `.env` needed)
|
||||
4. **Push image** to registry
|
||||
5. **Cleanup `.env` file** from runner
|
||||
|
||||
### Deployment Process
|
||||
|
||||
- Production server pulls pre-built image
|
||||
- No `.env` file needed on production server
|
||||
- Variables already embedded in JavaScript bundle
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### ✅ Implemented
|
||||
|
||||
- `.env` file created only in CI/CD runner (not committed to git)
|
||||
- `.env` cleaned up after Docker push
|
||||
- `.gitignore` excludes `.env` files
|
||||
- `.dockerignore` only allows `.env` created by CI/CD
|
||||
|
||||
### ⚠️ Important Notes
|
||||
|
||||
- **DO NOT commit `.env` files** to git repository
|
||||
- **DO NOT store secrets in `NEXT_PUBLIC_*` variables** (they are exposed to client-side)
|
||||
- **USE Gitea Secrets** for sensitive values (API keys, passwords)
|
||||
- **USE Gitea Variables** for non-sensitive config (URLs, feature flags)
|
||||
|
||||
### 🔒 Sensitive Data Guidelines
|
||||
|
||||
| Type | Use For | Access |
|
||||
|------|---------|--------|
|
||||
| `NEXT_PUBLIC_*` | Client-side config (URLs, feature flags) | Public (embedded in JS bundle) |
|
||||
| `SECRET_*` | Server-side secrets (API keys, DB passwords) | Private (runtime only) |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Variables not available during build
|
||||
|
||||
**Symptoms:**
|
||||
- Next.js build errors about missing `NEXT_PUBLIC_SITE_URL`
|
||||
- Metadata/sitemap generation fails
|
||||
|
||||
**Solution:**
|
||||
- Verify `NEXT_PUBLIC_SITE_URL` secret exists in Gitea
|
||||
- Check workflow logs for `.env` creation step
|
||||
- Ensure `.env` file is created BEFORE Docker build
|
||||
|
||||
### Issue: Variables not working in application
|
||||
|
||||
**Symptoms:**
|
||||
- URLs show as `undefined` or `null` in production
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if variable is in bundle (should work):
|
||||
curl https://yourdomain.com | grep -o 'NEXT_PUBLIC_SITE_URL'
|
||||
|
||||
# Check runtime env (should be empty - correct):
|
||||
docker exec mypage-prod node -e "console.log(process.env.NEXT_PUBLIC_SITE_URL)"
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
- Verify `.env` was copied during Docker build
|
||||
- Check Dockerfile logs for `COPY .env* ./` step
|
||||
- Rebuild with `--no-cache` if needed
|
||||
|
||||
### Issue: `.env` file not found during Docker build
|
||||
|
||||
**Symptoms:**
|
||||
- Docker build warning: `COPY .env* ./` - no files matched
|
||||
|
||||
**Solution:**
|
||||
- Check `.dockerignore` allows `.env` file
|
||||
- Verify workflow creates `.env` BEFORE Docker build
|
||||
- Check file exists: `ls -la .env` in workflow
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After deploying changes:
|
||||
|
||||
- [ ] Workflow creates `.env` file (check logs)
|
||||
- [ ] Docker build copies `.env` (check build logs)
|
||||
- [ ] Build succeeds without errors
|
||||
- [ ] Application starts in production
|
||||
- [ ] URLs/metadata display correctly
|
||||
- [ ] `.env` cleaned up after push (security)
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Next.js Environment Variables](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables)
|
||||
- [Docker Build Context](https://docs.docker.com/build/building/context/)
|
||||
- [Gitea Actions Secrets](https://docs.gitea.com/usage/actions/secrets)
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check workflow logs in Gitea Actions
|
||||
2. Review Docker build logs
|
||||
3. Verify Gitea secrets configuration
|
||||
4. Test locally with sample `.env`
|
||||
|
||||
**Last Updated:** 2025-11-24
|
||||
Reference in New Issue
Block a user