feat(config): implement configuration system and contributing guide (#6, #4)

2026-01-27 00:10:27 -08:00
parent 631046df34
commit 092299ff33
6 changed files with 767 additions and 2 deletions
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,203 @@
+# Configuration Setup Guide
+
+This guide explains how to set up your Nextcloud configuration for development and testing.
+
+## Quick Start
+
+1. **Copy the example configuration**:
+   ```bash
+   cp config.example.json config.json
+   ```
+
+2. **Generate a Nextcloud App Password** (recommended for security):
+   - Go to your Nextcloud instance
+   - Navigate to: **Settings → Security → Devices & sessions**
+   - Scroll to "App passwords" section
+   - Enter a name (e.g., "nextcloud-share-dev")
+   - Click "Create new app password"
+   - Copy the generated token
+
+3. **Edit `config.json`** with your credentials:
+   ```json
+   {
+     "nextcloud": {
+       "url": "https://cloud.tomusan.com",
+       "username": "your-username",
+       "password": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+     },
+     "settings": {
+       "maxRecentFolders": 5,
+       "uploadChunkSize": 10485760
+     }
+   }
+   ```
+
+4. **Validate your configuration**:
+   ```bash
+   ./scripts/validate-config.sh
+   ```
+
+## Generating App Passwords
+
+### For cloud.tomusan.com
+
+1. Log in to https://cloud.tomusan.com
+2. Click your profile icon (top right) → Settings
+3. Go to **Security** in the left sidebar
+4. Scroll down to **Devices & sessions**
+5. Under "App passwords" or "App-specific passwords":
+   - Enter a name: `nextcloud-share-dev`
+   - Click **Create new app password**
+6. Copy the generated password (format: `xxxxx-xxxxx-xxxxx-xxxxx-xxxxx`)
+7. Paste it into `config.json` as the `password` field
+
+### For disobedient.cloud/nextcloud
+
+1. Log in to https://disobedient.cloud/nextcloud
+2. Follow the same steps as above
+3. Generate a separate app password for this instance
+
+## Why App Passwords?
+
+App passwords are more secure than using your main account password because:
+
+- ✅ **Limited scope**: Only grants access to files, not account settings
+- ✅ **Revocable**: Can be revoked without changing your main password
+- ✅ **Traceable**: Shows up as a separate session in your account
+- ✅ **Safer storage**: If leaked, doesn't compromise your main account
+
+## Configuration Options
+
+### Required Fields
+
+- **`nextcloud.url`**: Your Nextcloud server URL (must use HTTPS in production)
+- **`nextcloud.username`**: Your Nextcloud username
+- **`nextcloud.password`**: App password or regular password
+
+### Optional Fields
+
+- **`settings.maxRecentFolders`**: Number of recent folders to remember (default: 5)
+- **`settings.uploadChunkSize`**: Upload chunk size in bytes (default: 10485760 = 10MB)
+
+## Environment Variable Overrides
+
+You can override any configuration value with environment variables (useful for CI/CD):
+
+```bash
+# Override config values
+export NEXTCLOUD_URL="https://cloud.example.com"
+export NEXTCLOUD_USER="testuser"
+export NEXTCLOUD_PASSWORD="app-password-here"
+
+# Run your tests
+./scripts/validate-config.sh
+```
+
+Environment variables always take precedence over `config.json`.
+
+## Loading Configuration
+
+To load configuration in your scripts:
+
+```bash
+#!/bin/bash
+source ./scripts/load-config.sh
+
+# Now you have access to:
+# - $NEXTCLOUD_URL
+# - $NEXTCLOUD_USER
+# - $NEXTCLOUD_PASSWORD
+# - $MAX_RECENT_FOLDERS
+# - $UPLOAD_CHUNK_SIZE
+```
+
+## Validating Configuration
+
+The validation script checks:
+
+- ✅ All required fields are present
+- ✅ URL format is valid
+- ✅ HTTPS is used (warns if HTTP)
+- ✅ Numeric settings are valid numbers
+
+```bash
+./scripts/validate-config.sh
+```
+
+## Security Notes
+
+- ⚠️ **Never commit `config.json`** - it's in `.gitignore`
+- ⚠️ **Use HTTPS**, not HTTP
+- ⚠️ **Use app passwords** when possible
+- ⚠️ **Revoke app passwords** when done with a project
+- ⚠️ Keep your `config.json` file permissions restricted:
+  ```bash
+  chmod 600 config.json
+  ```
+
+## Multiple Test Accounts
+
+If you have multiple Nextcloud instances for testing:
+
+**Option 1: Multiple config files**
+```bash
+cp config.example.json config-tomusan.json
+cp config.example.json config-disobedient.json
+
+# Use with:
+CONFIG_FILE=config-tomusan.json ./scripts/validate-config.sh
+```
+
+**Option 2: Environment variables**
+```bash
+export NEXTCLOUD_URL="https://disobedient.cloud/nextcloud"
+export NEXTCLOUD_USER="your-username"
+export NEXTCLOUD_PASSWORD="xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+
+./scripts/validate-config.sh
+```
+
+## Troubleshooting
+
+### "jq is not installed"
+
+Install jq on your system:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# macOS
+brew install jq
+
+# Arch Linux
+sudo pacman -S jq
+```
+
+### "NEXTCLOUD_URL must start with http:// or https://"
+
+Make sure your URL includes the protocol:
+- ✅ `https://cloud.tomusan.com`
+- ❌ `cloud.tomusan.com`
+
+### "Configuration is not valid"
+
+Run with the validation script to see specific errors:
+```bash
+./scripts/validate-config.sh
+```
+
+## CI/CD Configuration
+
+For Gitea Actions or other CI systems, set secrets in your repository:
+
+1. Go to repository **Settings → Secrets**
+2. Add these secrets:
+   - `NEXTCLOUD_TEST_URL`
+   - `NEXTCLOUD_TEST_USER`
+   - `NEXTCLOUD_TEST_PASSWORD`
+3. The CI will use environment variables instead of `config.json`
+
+---
+
+For more information, see [CONTRIBUTING.md](../CONTRIBUTING.md).