Granola CLI Deployment Guide

Overview

This guide covers deploying the Granola CLI using Docker Compose for both development and production environments. It emphasizes secure, reproducible workflows and leverages Make commands for convenience.
For authentication setup, see AUTHENTICATION.md. For project overview and CLI usage, see README.md.

---

Quick Start

Development Deployment

1. Clone and setup:

   git clone <repository-url>
   cd granola-cli
   cp .env.example .env
   

2. Configure environment (optional): Edit .env to customize paths.
3. Start development container:

   make up
   

4. Run CLI commands:

   make folders
   make notes
   

5. Stop container:

   make down
   

Production Deployment

1. Clone and setup:

   git clone <repository-url>
   cd granola-cli
   cp .env.example .env
   

2. Configure environment (optional): Edit .env to customize config paths.
3. Build and start production container:

   make prod-up
   

4. Run CLI commands:

   make prod-folders
   make prod-notes
   

5. Stop container:

   make prod-down
   

---

Docker Compose Workflows

Development Environment

• Uses docker-compose.yml and docker-compose.override.yml (auto-loaded).
• Source code is mounted for live reload.
• Config directory is mounted read-only from host:

  volumes:
    - "${HOME}/Library/Application Support/Granola:/granola-config:ro"
    - .:/app:cached
  

• Health checks and logs available via Make commands.

Production Environment

• Uses docker-compose.yml + docker-compose.prod.yml.
• Optimized, secure multi-stage build (Dockerfile.prod).
• Config directory mounted read-only:

  volumes:
    - "${GRANOLA_CONFIG_PATH:-${HOME}/Library/Application Support/Granola}:/granola-config:ro"
  

• Runs as non-root user, with resource limits and security hardening.
• Health checks, logging, and resource monitoring enabled.

Configuration

• Environment variables:

  Variable	Description	Default
  NODE_ENV	Node environment	production
  GRANOLA_CONFIG_PATH	Custom config path	Auto-detected
  DEBUG	Debug logging	Disabled

• Resource limits:

  • Development: 256MB memory, 0.5 CPU
  • Production: 128MB memory, 0.25 CPU

---

Docker Commands Reference

Command	Description
docker compose --profile development up --build	Start development container
docker compose --profile production up --build -d	Start production container
docker compose down	Stop containers
docker compose logs -f	View logs
docker compose exec granola-cli-dev sh	Access development shell
docker compose exec granola-cli-prod sh	Access production shell
docker compose exec granola-cli-dev granola folders	List folders (development)
docker compose exec granola-cli-prod granola folders	List folders (production)
docker compose exec granola-cli-dev granola notes	List notes (development)
docker compose exec granola-cli-prod granola notes	List notes (production)
docker compose ps	Check container status

NPM Script Shortcuts

Command	Description
npm run docker:dev	Start development container
npm run docker:prod	Start production container
npm run docker:stop	Stop containers
npm run docker:logs	View logs
npm run docker:shell	Access container shell

---

Container Configuration

Security Features

• Runs as non-root user (granola, UID 1001)
• Read-only filesystem and config mounts
• Dropped capabilities, no new privileges
• Resource limits (memory, CPU)
• Proper signal handling (dumb-init)
• Isolated bridge network, no exposed ports

Performance Optimizations

• Multi-stage builds for small images
• Layer caching for fast rebuilds
• Alpine Linux base for minimal attack surface
• Health checks and log rotation

Resource Management

• Monitor with docker stats granola-cli-prod
• Adjust limits in docker-compose.yml production profile as needed

---

Monitoring & Maintenance

Health Checks

• Built-in health checks (interval: 60s, timeout: 10s, retries: 2)
• Test: granola --version
• Check status:

  make health        # Development
  make prod-health   # Production
  

Logging

• Driver: json-file
• Max size: 10MB (dev), 5MB (prod)
• Max files: 3 (dev), 2 (prod)
• View logs:

  make logs         # Development
  make prod-logs    # Production
  

Resource Usage

• Monitor:

  docker stats granola-cli-prod
  

Updates

• Pull latest code and rebuild:

  git pull origin main
  make prod-down
  make prod-build
  make prod-up
  

• Clean unused Docker resources:

  docker system prune -f
  

---

Troubleshooting

Common Issues

• Authentication fails:

  • Check config mount in container:

    make shell         # Dev
    make prod-shell    # Prod
    ls -la /granola-config/
    

  • Verify host config permissions:

    ls -la "$HOME/Library/Application Support/Granola/"
    

  • See AUTHENTICATION.md for details.

• Build fails:

  • Clean and rebuild:

    make clean
    make build
    export DOCKER_BUILDKIT=1
    

• Container won't start:

  • Check logs:

    make logs         # Dev
    make prod-logs    # Prod
    

  • Check health:

    make health
    make prod-health
    

• Resource issues:

  • Monitor usage:

    docker stats granola-cli-prod
    

  • Adjust limits in compose files.

---

Best Practices

Development

1. Use override files for environment-specific config
2. Mount source code for hot reloading
3. Enable debug logging when troubleshooting
4. Use Make commands for consistency

Production

1. Use production Dockerfile for optimized builds
2. Set resource limits to prevent exhaustion
3. Enable health checks for monitoring
4. Use read-only mounts for security
5. Monitor logs regularly

Security

1. Never run as root in production
2. Use read-only filesystems when possible
3. Limit capabilities to minimum required
4. Mount volumes read-only when possible
5. Regularly update base images

---

For more details, see README.md, AUTHENTICATION.md, and CLI_SETUP.md.