nextcloud-share/docs/configuration.md

# 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).