From 5090d682d79c4ddecab60fcb35dbf7b37ab02b3f Mon Sep 17 00:00:00 2001
From: Alex Zaw <me@alexzaw.dev>
Date: Mon, 6 Apr 2026 18:05:36 +0000
Subject: [PATCH] Update README with full installation and usage docs

---
 README.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 113 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index db9de17..d1e9c60 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,114 @@
-# runtipi-onlyoffice-docs
+# ONLYOFFICE Docs for Runtipi
 
-Runtipi-compatible app configuration for ONLYOFFICE Document Server
\ No newline at end of file
+This is a Runtipi-compatible app configuration for [ONLYOFFICE Document Server](https://www.onlyoffice.com/office-suite.aspx).
+
+## Installation
+
+### Option 1: Via Runtipi App Store (if published)
+1. Search for "ONLYOFFICE Docs" in the Runtipi app store
+2. Click Install
+3. Configure your JWT secret and other options
+4. Start the app
+
+### Option 2: Manual Installation (Custom App Store)
+1. Copy the `onlyoffice-docs` folder to your Runtipi custom apps directory:
+   ```bash
+   cp -r onlyoffice-docs /path/to/runtipi/apps/
+   ```
+2. Restart Runtipi or refresh the app list
+3. Install from the UI
+
+### Option 3: Direct Docker Compose
+```bash
+cd onlyoffice-docs
+# Edit the .env file with your settings
+cp .env.example .env
+nano .env
+
+# Start with basic configuration (internal PostgreSQL)
+docker-compose up -d
+
+# Or use external database configuration for production
+docker-compose -f docker-compose.external-db.yml up -d
+```
+
+## Configuration
+
+### Required Settings
+
+| Variable | Description |
+|----------|-------------|
+| `ONLYOFFICE_JWT_SECRET` | Secret key for JWT authentication. **Required** for security. |
+
+### Optional Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONLYOFFICE_JWT_ENABLED` | `true` | Enable/disable JWT validation |
+| `ONLYOFFICE_JWT_HEADER` | `Authorization` | HTTP header for JWT token |
+| `ONLYOFFICE_JWT_IN_BODY` | `false` | Allow JWT in request body |
+| `ONLYOFFICE_USE_UNAUTHORIZED_STORAGE` | `false` | Accept self-signed certs |
+| `ONLYOFFICE_WOPI_ENABLED` | `false` | Enable WOPI protocol |
+
+## Integration Examples
+
+### Nextcloud Integration
+
+1. Install the ONLYOFFICE connector app in Nextcloud
+2. Go to Settings → ONLYOFFICE
+3. Configure:
+   - **Document Editing Service address**: `https://onlyoffice-docs.yourdomain.com` or `http://your-ip:8044`
+   - **Secret key**: Same as `ONLYOFFICE_JWT_SECRET`
+
+### Seafile Integration
+
+1. Add to `seahub_settings.py`:
+   ```python
+   ONLYOFFICE_APIJS_URL = 'https://onlyoffice-docs.yourdomain.com/web-apps/apps/api/documents/api.js'
+   ONLYOFFICE_JWT_SECRET = 'your-jwt-secret'
+   ```
+
+## File Structure
+
+```
+onlyoffice-docs/
+├── config.json                    # Runtipi app configuration
+├── docker-compose.yml             # Main compose file (self-contained)
+├── docker-compose.external-db.yml # Alternative with external DB
+├── description.md                 # App description for Runtipi UI
+├── .env.example                   # Example environment variables
+└── README.md                      # This file
+```
+
+## Data Persistence
+
+Data is stored in `${APP_DATA_DIR}/data/`:
+- `logs/` - Application logs
+- `data/` - Certificates and configuration
+- `lib/` - File cache and temporary files
+- `db/` - PostgreSQL database (basic config)
+- `fonts/` - Custom fonts
+
+## Troubleshooting
+
+### Container won't start
+- Check logs: `docker logs onlyoffice-docs`
+- Ensure port 8044 is not in use
+- Verify JWT_SECRET is set
+
+### Integration issues with Nextcloud
+- Ensure both services can reach each other
+- If using self-signed certs, enable `USE_UNAUTHORIZED_STORAGE`
+- Check that JWT secrets match exactly
+
+### Performance issues
+- Use the `docker-compose.external-db.yml` configuration
+- Increase container memory limits
+- Check disk I/O performance
+
+## Resources
+
+- [ONLYOFFICE Documentation](https://helpcenter.onlyoffice.com/docs/)
+- [Docker Hub](https://hub.docker.com/r/onlyoffice/documentserver)
+- [GitHub](https://github.com/ONLYOFFICE/DocumentServer)
+- [API Documentation](https://api.onlyoffice.com/)