b6a566db6e
- Add Dockerfile with multi-stage build - Add docker-compose.yml with Traefik labels - Add .dockerignore for optimal build context - Update next.config.ts for standalone output - Update DEPLOYMENT.md with Dokploy instructions Co-Authored-By: Claude <noreply@anthropic.com>
158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
# 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`:
|
|
|
|
```yaml
|
|
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)**
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://gitea.brachnha.com/Brachnha/brachnha-insight.git
|
|
cd brachnha-insight
|
|
|
|
# Build and start
|
|
docker-compose up -d
|
|
```
|
|
|
|
**Updating:**
|
|
|
|
```bash
|
|
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](https://vercel.com/new) 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**:
|
|
```bash
|
|
npm run build
|
|
```
|
|
2. **Start the server**:
|
|
```bash
|
|
npm start
|
|
```
|
|
The app will be available at `http://localhost:3000`.
|
|
|
|
Use a process manager like PM2 for production:
|
|
```bash
|
|
npm install -g pm2
|
|
pm2 start npm --name "brachnha-insights" -- start
|
|
pm2 startup
|
|
pm2 save
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Docker/Dokploy Issues
|
|
|
|
**Container won't start:**
|
|
```bash
|
|
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).
|