brachnha-insight/DEPLOYMENT.md

Deployment Instructions - Brachnha Insights

This guide provides instructions for deploying Brachnha Insights to production environments.

Prerequisites

• Node.js: v18 or higher
• npm: v9 or higher
• Docker & Docker Compose (for Dokploy deployment)

Environment Variables

Ensure the following environment variables are configured in your production environment:

Variable	Description	Default / Example
NEXT_PUBLIC_AI_PROVIDER	Default AI Provider (optional)	gemini
NEXT_PUBLIC_GEMINI_API_KEY	Initial API Key (optional)	AIzaSy...
NEXT_PUBLIC_API_URL	API Base URL (if custom)	https://api.example.com

Note: The application uses a local-first architecture (IndexedDB), so no external database connection strings (Postgres/MySQL) are required for the core journaling features.

---

Deployment Options

Option 1: Dokploy with Docker Compose (Recommended for Self-Hosting)

Dokploy provides an easy way to deploy and manage your applications with Docker.

Files Included

• Dockerfile - Multi-stage build for optimal image size
• docker-compose.yml - Service configuration with Traefik labels
• .dockerignore - Excludes unnecessary files from build

Deployment Steps

1. Deploy from Git Repository (Recommended)

In your Dokploy Dashboard:

• Click "Create Project"
• Select "Compose" as project type
• Choose "From Git Repository"
• Enter your Git URL: https://gitea.brachnha.com/Brachnha/brachnha-insight.git
• Add your Git credentials (token)
• Set branch to master
• Click "Create"

2. Configure Domain (Optional)

Edit docker-compose.yml and replace your-domain.com:

labels:
  - "traefik.http.routers.brachnha-insights.rule=Host(`insights.brachnha.com`)"

3. Deploy

• Click "Deploy" button in Dokploy
• Dokploy will build and start the container

Manual Deployment (Alternative)

# Clone repository
git clone https://gitea.brachnha.com/Brachnha/brachnha-insight.git
cd brachnha-insight

# Build and start
docker-compose up -d

Updating:

git pull origin master
docker-compose down
docker-compose build
docker-compose up -d

Or trigger a redeploy from the Dokploy dashboard.

---

Option 2: Vercel (Recommended for Managed Hosting)

Vercel provides the best support for Next.js applications, including PWA headers and caching.

1. Push to GitHub: Ensure your code is pushed to a remote repository.
2. Import Project: Go to Vercel Dashboard and import your repository.
3. Configure:
   • Framework Preset: Next.js
   • Build Command: next build
   • Output Directory: .next
   • Environment Variables: Add any keys defined above.
4. Deploy: Click "Deploy".

Vercel will automatically detect the manifest.webmanifest and service worker configurations.

---

Option 3: Traditional Node.js Server

To deploy as a standalone Node.js application:

1. Build the application:

   npm run build
   

2. Start the server:

   npm start
   

   The app will be available at http://localhost:3000.

Use a process manager like PM2 for production:

npm install -g pm2
pm2 start npm --name "brachnha-insights" -- start
pm2 startup
pm2 save

---

Troubleshooting

Docker/Dokploy Issues

Container won't start:

docker-compose logs brachnha-insights

Build fails:

• Ensure next.config.ts has output: 'standalone'
• Check that all dependencies are in package.json

Port conflicts:

• Change the port mapping in docker-compose.yml
• Update the Traefik labels accordingly

Build Failures

• Google Fonts / Network Errors: The build process requires internet access to download fonts from Google. If building in a restricted environment (like a corporate firewall or offline CI), you may see TLS/Network errors.

  • Workaround: Set NEXT_TURBOPACK_EXPERIMENTAL_USE_SYSTEM_TLS_CERTS=1 or temporarily disable next/font/google in src/app/layout.tsx.

• Manifest Errors: If you see manifest.ts type errors, ensure you are using a compatible Next.js version (14+ recommended) or check purpose fields in icon definitions.

PWA Verification

After deployment, verify the PWA features:

1. Open the deployed URL on a mobile device or Chrome.
2. Look for the "Install Brachnha Insights" prompt (bottom banner) or the Install icon in the address bar.
3. Install the app and verify it opens in standalone mode.
4. Disconnect internet and verify you can still create/save drafts (Offline support).