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:

   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:

   {
     "nextcloud": {
       "url": "https://cloud.tomusan.com",
       "username": "your-username",
       "password": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
     },
     "settings": {
       "maxRecentFolders": 5,
       "uploadChunkSize": 10485760
     }
   }
   

4. Validate your configuration:

   ./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):

# 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:

#!/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

./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:

  chmod 600 config.json
  

Multiple Test Accounts

If you have multiple Nextcloud instances for testing:

Option 1: Multiple config files

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

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:

# 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:

./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.