AgapHost/overleaf/README.md

# Overleaf Service

Overleaf is an open-source online LaTeX editor. This directory contains the Docker Compose configuration for running Overleaf on Agap.

## Configuration Files

- **`.env`** - Docker Compose environment variables (image versions, ports, data paths)
- **`docker-compose.yml`** - Service definitions (Overleaf, MongoDB, Redis)
- **`overleaf.rc`** - Overleaf toolkit configuration (compatibility layer)
- **`variables.env`** - Overleaf application environment variables
- **`version`** - Overleaf image version (6.1.2)

## Data Directories

The following directories must exist on the host and have appropriate permissions:

```
/mnt/ssd/dbs/overleaf/
├── data/              # Overleaf application data
├── mongo/             # MongoDB database files
└── redis/             # Redis persistence files
```

Create them if they don't exist:
```bash
mkdir -p /mnt/ssd/dbs/overleaf/{data,mongo}
mkdir -p /mnt/ssd/dbs/overleaf/redis
chmod 755 /mnt/ssd/dbs/overleaf/*
```

## Quick Start

From the `agap_git/overleaf/` directory:

```bash
# Start all services (compose reads .env automatically)
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f sharelatex

# Stop all services
docker compose down
```

## Services

### sharelatex
- **Image**: `sharelatex/sharelatex:6.1.2`
- **Port**: `127.0.0.1:8089` (localhost only)
- **Data**: `/mnt/ssd/dbs/overleaf/data:/var/lib/overleaf`
- **Features**:
  - Sandboxed compiles via Docker sibling containers
  - Email disabled by default (see `variables.env`)
  - Templates and project files enabled (see `variables.env`)

### mongo
- **Image**: `mongo:8.0`
- **Port**: `27017` (internal, exposed only to sharelatex)
- **Data**: `/mnt/ssd/dbs/overleaf/mongo:/data/db`
- **Replica Set**: Initialized automatically on first run with `--replSet overleaf`

### redis
- **Image**: `redis:7.4`
- **Port**: `6379` (internal, exposed only to sharelatex)
- **Data**: `/mnt/ssd/dbs/overleaf/redis:/data`
- **Persistence**: AOF (Append-Only File) enabled

## Configuration

### Environment Variables

Edit `variables.env` to customize Overleaf behavior:

- `OVERLEAF_APP_NAME` - Display name for the instance
- `ENABLE_CONVERSIONS` - Enable PDF thumbnail generation
- `EMAIL_CONFIRMATION_DISABLED` - Disable email confirmation requirement
- `OVERLEAF_SITE_URL` - Public URL (if behind proxy)
- `OVERLEAF_BEHIND_PROXY` - Set to true if behind reverse proxy
- `OVERLEAF_SECURE_COOKIE` - Use secure cookies when behind TLS proxy

### Port Binding

The `OVERLEAF_LISTEN_IP` in `.env` controls which interface Overleaf listens on:
- `127.0.0.1` - Localhost only (default, requires reverse proxy)
- `0.0.0.0` - All interfaces (not recommended without TLS)

### Storage

All data is stored on `/mnt/ssd/dbs/overleaf/`:
- Application data (documents, projects)
- MongoDB replica set database
- Redis cache and session data

## Maintenance

### Backup

To back up Overleaf data:

```bash
# Stop services gracefully
docker compose stop

# Backup directories
tar czf overleaf-backup-$(date +%Y%m%d).tar.gz /mnt/ssd/dbs/overleaf/

# Restart
docker compose up -d
```

### Upgrade Image Version

To upgrade the Overleaf image:

1. Edit `.env` and update `SHARELATEX_IMAGE` version tag
2. Pull the new image: `docker compose pull`
3. Recreate the service: `docker compose up -d`
4. MongoDB and Redis require no migration for patch/minor version bumps

### Database Replica Set

MongoDB is configured with a single-node replica set (`--replSet overleaf`) which is required by Overleaf. If MongoDB fails to initialize:

```bash
docker compose exec mongo mongosh --eval "rs.initiate({ _id: 'overleaf', members: [ { _id: 0, host: 'mongo:27017' } ] })"
```

## Troubleshooting

### Overleaf won't start
```bash
# Check logs
docker compose logs sharelatex

# Common issues:
# - MongoDB not ready (check mongo logs)
# - Redis not ready (check redis logs)
# - Data volume permissions (check /mnt/ssd/dbs/overleaf/ permissions)
```

### High memory usage
- Redis AOF file can grow; use `BGREWRITEAOF` if needed
- MongoDB maintenance: run `db.collection.reIndex()` for indexed collections

### Replica set errors in logs
Safe to ignore on first startup; it initializes automatically. If persistent:
```bash
docker compose restart mongo
```

## Notes

- This is Overleaf **Community Edition** (SERVER_PRO=false in overleaf.rc)
- Sibling container sandboxing is enabled but uses single-node mode
- No TLS termination (nginx proxy is disabled); use Caddy or another reverse proxy
- Email is disabled by default; configure SMTP in variables.env to enable

## References

- [Overleaf Toolkit Documentation](https://github.com/overleaf/toolkit)
- [Overleaf GitHub Wiki](https://github.com/overleaf/overleaf/wiki)