Jotty Deployment & Usage Guide

1. Prerequisites

Runtime & Tools:

• Docker (recommended) or Docker Compose for containerized deployment
• Node.js 18+ and npm for local development
• Git for cloning the repository

Accounts (Optional):

• GitHub account (for accessing ghcr.io/fccview/jotty container image)
• OIDC provider account (if using Single Sign-On)

Permissions:

• Ability to create directories and set file permissions (for data persistence)
• Port access (default: 1122 for Docker, 3000 for development)

2. Installation

Docker Installation (Recommended)

1. Create a docker-compose.yml file:

services:
  jotty:
    image: ghcr.io/fccview/jotty:latest
    container_name: jotty
    user: "1000:1000"
    ports:
      - "1122:3000"
    volumes:
      - ./data:/app/data:rw
      - ./config:/app/config:rw
      - ./cache:/app/.next/cache:rw
    restart: unless-stopped
    environment:
      - NODE_ENV=production

2. Create required directories and set permissions:

mkdir -p config data/users data/checklists data/notes data/sharing data/encryption cache
sudo chown -R 1000:1000 data/
sudo chown -R 1000:1000 config/
sudo chown -R 1000:1000 cache/

Note: The cache directory is optional. Remove the cache volume line from docker-compose.yml if you don't want cache persistence.

3. Start the container:

docker compose up -d

The application will be available at http://localhost:1122.

Alternative Installation Methods

• Proxmox VE: Use the community script
• Unraid: Follow the Unraid template instructions

3. Configuration

Environment Variables

Add these to your docker-compose.yml under the environment section:

environment:
  - NODE_ENV=production
  # Optional: SSO Configuration
  - OIDC_ISSUER=https://your-oidc-provider.com
  - OIDC_CLIENT_ID=your_client_id
  - OIDC_CLIENT_SECRET=your_client_secret
  # Optional: Custom port (if not using Docker port mapping)
  - PORT=3000

File Structure Configuration

Jotty uses a specific directory structure:

data/
├── checklists/     # Stores all checklists as .md files
├── notes/          # Stores all notes as .md files
├── users/          # Contains users.json and sessions.json
├── sharing/        # Contains shared-items.json
└── encryption/     # Contains PGP keys for all users

Initial Setup

1. Access http://your-server:1122 (or your configured port)
2. If SSO is disabled, you'll be redirected to /auth/setup to create your admin account
3. The first user created becomes the administrator by default
4. If SSO is enabled, you'll be prompted to sign in via your configured provider

4. Build & Run (Development)

Clone and Setup

# Clone the repository
git clone https://github.com/fccview/jotty.git
cd jotty

# Install dependencies
npm install

# Create data directories
mkdir -p data/{users,checklists,notes,sharing,encryption}

Development Mode

# Start development server
npm run dev

The app will be available at http://localhost:3000 with hot reload enabled.

Production Build

# Build the application
npm run build

# Start production server
npm start

5. Deployment

Docker-Based Deployment Platforms

Recommended Platforms:

1. Self-hosted Docker: Any Linux server with Docker installed
2. Portainer: For GUI-based Docker management
3. Docker Swarm/Kubernetes: For clustered deployments
4. Cloud Platforms:
   • AWS ECS/EKS
   • Google Cloud Run
   • Azure Container Instances
   • DigitalOcean App Platform

Docker Deployment Example

# Pull the latest image
docker pull ghcr.io/fccview/jotty:latest

# Run with persistent volumes
docker run -d \
  --name jotty \
  -p 1122:3000 \
  -v /path/to/data:/app/data \
  -v /path/to/config:/app/config \
  -e NODE_ENV=production \
  --restart unless-stopped \
  ghcr.io/fccview/jotty:latest

Reverse Proxy Setup (Recommended for Production)

Use Nginx or Traefik as a reverse proxy:

Nginx Configuration:

server {
    listen 80;
    server_name jotty.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:1122;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Backup Strategy

Critical: Regularly back up your data/ directory. This contains all user data, notes, checklists, and encryption keys.

# Example backup script
tar -czf jotty-backup-$(date +%Y%m%d).tar.gz /path/to/data/

6. Troubleshooting

Common Issues

1. Permission Errors

# Fix directory permissions
sudo chown -R 1000:1000 /path/to/data/
sudo chown -R 1000:1000 /path/to/config/

2. Port Already in Use

# Check what's using port 1122
sudo lsof -i :1122

# Or change the port in docker-compose.yml
ports:
  - "1123:3000"  # Changed from 1122 to 1123

3. Container Won't Start

# Check container logs
docker logs jotty

# Check for syntax errors in docker-compose.yml
docker compose config

4. Migration Issues (Version 1.11.0+) If you encounter migration problems:

# Check migration status
cat data/.migration

# Manual migration may be required
# See app/_server/actions/migration/index.ts for migration logic

5. Data Not Persisting

• Ensure volumes are correctly mounted in Docker
• Check that the data/ directory has proper write permissions
• Verify the user ID (1000:1000) matches your system user

6. SSO/OIDC Issues

• Verify OIDC environment variables are correctly set
• Check that your OIDC provider allows the redirect URI
• Review browser console and server logs for authentication errors

7. API Access Problems

• Ensure you're using the correct authentication tokens
• Check that the user has appropriate permissions for the requested resource
• Verify the API endpoint matches your deployment URL

Logs and Debugging

# Docker container logs
docker logs jotty -f

# Check container status
docker ps -a | grep jotty

# Enter container for debugging
docker exec -it jotty /bin/sh

# Check file permissions inside container
docker exec jotty ls -la /app/data/

Performance Issues

1. Enable Cache Persistence: Use the cache volume as shown in the Docker Compose example
2. Database Optimization: Since Jotty is file-based, ensure your storage has good I/O performance (SSD recommended)
3. Memory Limits: Monitor memory usage, especially with many concurrent users

Getting Help

• Discord: Join Community
• Reddit: /r/jotty
• Telegram: @jottypage
• GitHub Issues: Check existing issues or create new ones

Remember: Always back up your data/ directory before making significant changes or updates!