Codakey
Play
← Back to dashwise-next

How to Deploy & Use dashwise-next

Dashwise Deployment and Usage Guide

1. Prerequisites

Before installing Dashwise, ensure you have the following:

  • Docker and Docker Compose installed on your system
  • Node.js 18+ (if running without Docker)
  • A modern web browser (Chrome, Firefox, Safari, or Edge)
  • Basic familiarity with Docker container management
  • (Optional) SSL certificates if you plan to enable HTTPS

2. Installation

Docker Installation (Recommended)

  1. Download the production Docker Compose file:

    curl -O https://raw.githubusercontent.com/andreasmolnardev/dashwise-next/main/docker-compose.prod.yaml

  2. Edit environment variables in the downloaded file (see Configuration section below).

  3. Deploy the stack:

    docker-compose -f docker-compose.prod.yaml up -d

Manual Installation (Development)

  1. Clone the repository:

    git clone https://github.com/andreasmolnardev/dashwise-next.git
cd dashwise-next

  2. Install dependencies:

    npm install

  3. Set up PocketBase backend:

    • Download PocketBase from pocketbase.io
    • Start PocketBase in a separate terminal: 
      ./pocketbase serve

  4. Configure environment variables (create .env.local file).

3. Configuration

Environment Variables

Create a .env.local file in the project root or set these variables in your Docker Compose file:

Main Application Container:

# Required
NEXT_PUBLIC_PB_URL=http://pocketbase:8090  # URL of your PocketBase instance
PB_ADMIN_EMAIL=admin@yourdomain.local      # PocketBase admin email
PB_ADMIN_PASSWORD=YourSecurePassword       # PocketBase admin password
NEXT_PUBLIC_APP_URL=http://localhost:3000  # Public URL of your Dashwise instance

# Optional
NEXT_PUBLIC_INTEGRATIONS_ENABLE_SSL=false  # Enable SSL for integrations
NEXT_PUBLIC_ENABLE_SSO=false               # Enable Single Sign-On via OIDC
NEXT_PUBLIC_DEFAULT_BG_URL=/dashboard-wallpaper.png  # Default background
NEXT_PUBLIC_JOBS_WEBHOOK_ENABLE=false      # Enable jobs webhook
NEXT_PUBLIC_JOBS_URL=http://127.0.0.1:3001 # Jobs webhook endpoint

Jobs Container (for background tasks):

# Required
PB_URL=http://pocketbase:8090              # Internal PocketBase URL
DASHWISE_URL=http://dashwise:3000          # Internal Dashwise URL
PB_ADMIN_EMAIL=admin@yourdomain.local      # PocketBase admin email
PB_ADMIN_PASSWORD=YourSecurePassword       # PocketBase admin password

# Optional - Cron schedules
SEARCHITEMS_SCHEDULE=*/10 * * * *          # Search indexing interval
MONITORING_INDEXER_SCHEDULE=*/10 * * * *   # Monitoring indexer interval
MONITORING_RUNNER_SCHEDULE=*/1 * * * *     # Monitoring runner interval
ALLOW_SSL=false                            # Enable SSL for internal communication

Service Integrations

Dashwise supports integration with several self-hosted services. To configure integrations:

  1. Access the Dashwise web interface after initial setup
  2. Navigate to Settings → Integrations
  3. Configure each service with the required connection details:
    • Karakeep: URL and authentication details
    • Dashdot: URL of your Dashdot instance
    • Beszel: URL, email, and password for PocketBase authentication
    • Jellyfin: Server URL and API key

Authentication Configuration

For SSO/OIDC setup:

  1. Configure OIDC in PocketBase admin interface
  2. Set NEXT_PUBLIC_ENABLE_SSO=true
  3. Ensure your OIDC provider returns the required claims

4. Build & Run

Development Mode

  1. Start the development server:

    npm run dev

  2. Access the application at http://localhost:3000

  3. Build for production:

    npm run build

Production Mode

  1. Build the application:

    npm run build

  2. Start the production server:

    npm start

Using Docker Build

  1. Build the Docker image:

    docker build -t dashwise:latest .

  2. Run the container:

    docker run -p 3000:3000 --env-file .env.local dashwise:latest

5. Deployment

Docker Compose Deployment (Recommended for Homelabs)

  1. Customize the Docker Compose file for your environment:

    • Update volume mounts for persistent data
    • Configure network settings
    • Set appropriate resource limits

  2. Deploy with Docker Compose:

    docker-compose -f docker-compose.prod.yaml up -d

  3. Set up a reverse proxy (nginx, Traefik, or Caddy) for SSL termination and domain routing.

Platform Recommendations

  • Self-hosted/VPS: Docker Compose with nginx reverse proxy
  • Kubernetes: Create deployments for dashwise, pocketbase, and jobs containers
  • Docker Swarm: Use stack files for orchestration
  • Traditional VM: Node.js + PM2 for process management

Persistent Data

Ensure these volumes are persisted:

  • PocketBase data (pb_data volume)
  • Uploaded wallpapers and user content
  • Database backups

SSL Configuration

  1. Obtain SSL certificates (Let's Encrypt recommended)
  2. Configure reverse proxy for HTTPS termination
  3. Update NEXT_PUBLIC_APP_URL to use https://
  4. Set NEXT_PUBLIC_INTEGRATIONS_ENABLE_SSL=true if services use HTTPS

6. Troubleshooting

Common Issues

1. PocketBase Connection Errors

Error: Failed to connect to PocketBase

Solution:

  • Verify PocketBase is running: docker ps | grep pocketbase
  • Check PocketBase logs: docker logs <pocketbase_container_name>
  • Ensure NEXT_PUBLIC_PB_URL matches the internal Docker network address

2. Authentication Failures

Unauthorized error when accessing /api/v1/config

Solution:

  • Verify admin credentials in environment variables
  • Check PocketBase admin user exists: docker exec <pocketbase_container> pocketbase admin list
  • Reset admin password if needed: docker exec <pocketbase_container> pocketbase admin update --email admin@yourdomain.local --password newpassword

3. Jobs Container Not Running

Background tasks (link monitoring, search indexing) not working

Solution:

  • Check jobs container logs: docker logs dashwise-jobs
  • Verify cron schedules in environment variables
  • Ensure PB_URL and DASHWISE_URL are accessible from the jobs container

4. Integration Connection Issues

Failed to connect to Beszel/Karakeep/Jellyfin

Solution:

  • Verify the service URL is correct and accessible
  • Check authentication credentials
  • For Beszel, ensure PocketBase authentication details are correct
  • Enable NEXT_PUBLIC_INTEGRATIONS_ENABLE_SSL if using HTTPS

5. Build Errors

TypeScript compilation errors during npm run build

Solution:

  • Clear node_modules and reinstall: rm -rf node_modules && npm install
  • Check Node.js version: node --version (requires 18+)
  • Update dependencies: npm update

6. Container Port Conflicts

Port 3000 or 8090 already in use

Solution:

  • Change port mappings in Docker Compose file
  • Stop conflicting services: sudo lsof -i :3000
  • Use different host ports

Logs and Debugging

  1. View application logs:

    docker logs dashwise-app

  2. View PocketBase logs:

    docker logs pocketbase

  3. View jobs container logs:

    docker logs dashwise-jobs

  4. Enable verbose logging by adding to environment:

    NODE_ENV=development
DEBUG=true

Database Issues

  1. Reset PocketBase data (warning: deletes all data):

    docker-compose down -v
docker-compose up -d

  2. Backup PocketBase data:

    docker exec <pocketbase_container> pocketbase backup backup.db

  3. Restore from backup:

    docker exec <pocketbase_container> pocketbase restore backup.db

Performance Issues

  1. High memory usage:

    • Increase container memory limits in Docker Compose
    • Monitor with docker stats

  2. Slow dashboard loading:

    • Check network connectivity between containers
    • Verify jobs container is running (handles background indexing)
    • Reduce number of monitored links if using link monitoring

Getting Help

  • Check existing issues on GitHub
  • Review the PocketBase documentation
  • Enable debug logging and share logs when reporting issues
← Project overviewView alternatives to dashwise-next →