Installation Guide - NateEaton/mind-pwa GitHub Wiki

How to Install the Application

This guide provides complete instructions for installing and setting up the MIND Diet Tracker application.

For End Users

Most users don't need to install anything - you can use the app directly.

Where to Access the App

Option 1: Use the Hosted Demo (Recommended)

  • URL: https://mind-pwa-fawn.vercel.app/
  • Features: Complete MIND Diet tracking, local data storage, import/export
  • Limitations: No cloud sync (client-only deployment)
  • Setup: Just open the URL and start using

Option 2: Use a Self-Hosted Instance

  • If someone has provided you with a self-hosted instance URL, simply navigate to it and follow the setup wizard
  • May include cloud sync features depending on how it's deployed

How to Use the App

In Your Browser:

  • Open any of the above URLs in any modern web browser
  • Works on desktop and mobile
  • Requires internet connection for initial load

As a PWA (Progressive Web App):

  • Install the app on your device for a native app-like experience
  • Works offline after installation
  • No browser address bar or tabs

PWA Installation:

  • Mobile (iOS): Open Safari, navigate to the app URL, tap Share → "Add to Home Screen"
  • Mobile (Android): Open Chrome, navigate to the app URL, tap Menu → "Add to Home Screen"
  • Desktop: Look for the install icon in your browser's address bar (Chrome, Edge, Firefox)

For Self-Hosting

This section covers everything needed to host your own instance from scratch.

Deployment Types

The MIND Diet Tracker supports two deployment types:

Client-Only Deployment:

  • Local data storage with import/export capabilities
  • Perfect for static hosting platforms (Vercel, Netlify, NAS)
  • No server-side components required
  • Use if: You don't need cloud sync or want simple hosting

Server-Enabled Deployment:

  • All client-only features plus cloud synchronization
  • Requires OAuth server and cloud provider credentials
  • Supports Google Drive and Dropbox sync
  • Use if: You want cross-device synchronization

Prerequisites

For Both Deployment Types:

  • Git installed
  • Node.js 18 or higher
  • Basic command line knowledge

Additional for Server-Enabled:

  • Domain name with HTTPS support (required for OAuth)
  • Google and/or Dropbox developer accounts
  • For Docker: Docker and Docker Compose installed

Step 1: Clone Repository

git clone https://github.com/NateEaton/mind-pwa.git
cd mind-pwa

Step 2: Install Dependencies

# Install root dependencies
npm install

# Install server dependencies (if using server-enabled deployment)
cd server
npm install
cd ..

Step 3: Environment Configuration

Create a .env file in the project root:

For Client-Only Deployment:

# Client-only deployment configuration
VITE_SERVER_FEATURES_ENABLED=false
VITE_DEV_MODE=false

For Server-Enabled Deployment:

# Server-enabled deployment configuration
VITE_SERVER_FEATURES_ENABLED=true
VITE_DEV_MODE=false

# Your application domain (required for OAuth)
APP_BASE_URL=https://yourdomain.com

# Google Drive API credentials (optional - only if you want Google Drive sync)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Dropbox API credentials (optional - only if you want Dropbox sync)  
DROPBOX_CLIENT_ID=your_dropbox_app_key
DROPBOX_CLIENT_SECRET=your_dropbox_app_secret

Step 4: OAuth Provider Setup (Server-Enabled Only)

If you want cloud synchronization, you need to set up API credentials with cloud providers.

Google Drive API Setup

  1. Create a Google Cloud Project:

    • Go to the Google Cloud Console
    • Click "Select a project" → "New Project"
    • Enter a project name and click "Create"
    • Select your new project

  2. Enable the Google Drive API:

    • In the sidebar, go to "APIs & Services" → "Library"
    • Search for "Google Drive API"
    • Click on it and click "Enable"

  3. Create OAuth Credentials:

    • Go to "APIs & Services" → "Credentials"
    • Click "Create Credentials" → "OAuth client ID"
    • If prompted, configure the OAuth consent screen first:
      • Choose "External" user type
      • Fill in required fields (app name, user support email, developer email)
      • Add your domain to authorized domains
      • Save and continue through the scopes and test users screens
    • For the OAuth client ID:
      • Application type: "Web application"
      • Name: "MIND Diet Tracker" (or your preferred name)
      • Authorized JavaScript origins: https://yourdomain.com
      • Authorized redirect URIs: https://yourdomain.com/api/gdrive/callback
    • Click "Create" and copy the Client ID and Client Secret
    • Add these to your .env file as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

Dropbox API Setup

  1. Create a Dropbox App:

    • Go to the Dropbox Developer Console
    • Click "Create app"
    • Choose "Scoped access" API
    • Choose "App folder" access type (recommended for security)
    • Enter an app name
    • Click "Create app"

  2. Configure App Settings:

    • In the "Settings" tab, add your redirect URI:
      • Redirect URIs: https://yourdomain.com/api/dropbox/callback
    • In the "Permissions" tab, enable:
      • files.metadata.read
      • files.metadata.write
      • files.content.read
      • files.content.write
    • Click "Submit" to save permissions

  3. Get Your Credentials:

    • In the "Settings" tab, copy the "App key" and "App secret"
    • Add these to your .env file as DROPBOX_CLIENT_ID and DROPBOX_CLIENT_SECRET

Step 5: Build the Application

For Client-Only Deployment:

# Build client-only version
./deploy-client.sh

For Server-Enabled Deployment:

# Build server-enabled version
./deploy-server.sh

The build process will:

  • Install dependencies
  • Build the client application with appropriate features
  • Copy files to the deployment directory

Step 6: Deploy

Option A: Docker Deployment (Recommended)

Client-Only:

# Start nginx container serving the built files
./start-client-only.sh
# Access at http://your-server-ip:8080

Server-Enabled:

# Start containers (nginx + Node.js OAuth server)
./start-server.sh  
# Access at https://yourdomain.com

Option B: Traditional Web Server

Client-Only:

  1. Run the deployment script: ./deploy-client.sh
  2. Configure your web server to serve files from the deployment directory
  3. Ensure HTTPS is configured for PWA features

Server-Enabled:

  1. Run the deployment script: ./deploy-server.sh
  2. Configure your web server to proxy OAuth requests to the Node.js server:
    • Proxy /api/gdrive/* to http://localhost:3000/api/gdrive/*
    • Proxy /api/dropbox/* to http://localhost:3000/api/dropbox/*
  3. Start the OAuth server: 
    cd server
npm start
  4. Ensure HTTPS is configured (required for OAuth)

Note: The deployment scripts automatically copy built files to /volume1/web/mind-pwa-deploy/ (configured for Synology NAS). Edit the scripts to change the target directory for other systems.

Example Nginx Configuration (Server-Enabled)

server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    # SSL configuration
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    
    # Serve client files
    location / {
        root /path/to/client/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # Proxy OAuth requests to Node.js server
    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Step 7: Verification

  1. Access the application at your configured URL

  2. Complete the setup wizard - it should run automatically on first visit

  3. Test basic functionality:

    • Add some food servings in the Daily view
    • Check that Weekly view shows your totals
    • Verify data persists after page refresh

  4. Test cloud sync (server-enabled deployments only):

    • In the setup wizard or Settings, enable cloud sync
    • Select a provider and authenticate
    • Verify the status shows "Connected"
    • Try "Sync Now" to test the connection

Environment Variables Reference

Client Environment Variables (Vite):

  • VITE_SERVER_FEATURES_ENABLED: true or false - Controls cloud sync feature inclusion
  • VITE_DEV_MODE: true or false - Enables development features
  • VITE_APP_BASE_URL: Your application URL (typically same as APP_BASE_URL)

Server Environment Variables (Node.js):

  • APP_BASE_URL: Your application's public URL (e.g., https://yourdomain.com)
  • GOOGLE_CLIENT_ID: OAuth client ID from Google Cloud Console
  • GOOGLE_CLIENT_SECRET: OAuth client secret from Google Cloud Console
  • DROPBOX_CLIENT_ID: App key from Dropbox Developer Console
  • DROPBOX_CLIENT_SECRET: App secret from Dropbox Developer Console

Notes:

  • Client variables are processed at build time by Vite
  • Server variables are loaded at runtime from the .env file
  • All VITE_* variables are accessible in the client code
  • Server variables are only required for server-enabled deployments

Deployment Platform Guides

Vercel/Netlify (Client-Only)

  • Build Command: cd client && npm run build
  • Output Directory: client/dist
  • Environment Variables: Set VITE_SERVER_FEATURES_ENABLED=false

GitHub Pages (Client-Only)

  1. Build locally: ./deploy-client.sh
  2. Copy client/dist/ contents to your repository
  3. Enable GitHub Pages in repository settings

Home Server/NAS (Client-Only)

The deployment scripts are configured for Synology NAS paths. For other systems:

  1. Edit deploy-client.sh to change the target directory
  2. Ensure your web server serves files from that directory

Troubleshooting

Build Issues

"Command not found" errors:

  • Ensure Node.js 18+ is installed: node --version
  • Make sure you're in the project root directory
  • Try npm install to install dependencies

Permission errors on deployment scripts:

  • Make scripts executable: chmod +x deploy-*.sh start-*.sh

OAuth Setup Issues

Google Drive authentication not working:

  • Verify redirect URI exactly matches: https://yourdomain.com/api/gdrive/callback
  • Check that OAuth consent screen is configured
  • Ensure Google Drive API is enabled in your project

Dropbox authentication not working:

  • Verify redirect URI exactly matches: https://yourdomain.com/api/dropbox/callback
  • Check that required permissions are enabled in the Dropbox app
  • Ensure you submitted the permissions after enabling them

Runtime Issues

App loads but cloud sync unavailable:

  • Check that VITE_SERVER_FEATURES_ENABLED=true in your .env file
  • Rebuild the application after changing environment variables
  • Verify the OAuth server is running (server-enabled deployments)

PWA features not working:

  • Ensure the app is served over HTTPS
  • Check browser compatibility (Chrome, Edge, Safari 16.4+)
  • Clear browser cache and try again

Data not persisting:

  • Ensure you're not in private/incognito mode
  • Check available storage space on your device
  • Verify browser settings allow local storage

Docker Issues

Container won't start:

  • Check that all environment variables are set in .env
  • Verify Docker and Docker Compose are installed
  • Check logs: docker-compose logs

Can't access the app:

  • Verify your domain DNS is pointing to your server
  • Check firewall settings (ports 80, 443)
  • Ensure SSL certificate is valid

Security Considerations

Production Deployment:

  • Always use HTTPS in production (required for OAuth and PWA features)
  • Keep your OAuth credentials secure and never commit them to version control
  • Use environment variables for all sensitive configuration
  • Regularly update dependencies: npm audit and npm update

OAuth Security:

  • Restrict OAuth redirect URIs to your exact domain
  • Use the principle of least privilege for API permissions
  • Monitor your cloud provider's API usage for unusual activity

Server Security:

  • Keep your server and dependencies updated
  • Use a firewall to restrict access to necessary ports only
  • Monitor server logs for unusual activity
  • Consider using a reverse proxy like nginx for additional security