Project Resources

• OpenSGF: Join our weekly meetings!
• Code of Conduct: Please read before participating
• Discord: Click "Join" on OpenSGF website
• Project Documentation: Product Requirement Documents (PRDs)
• Project Management: Claim a PRD and/or update PRD status here
• Dropbox App Setup: End-user setup and authorization guide for Dropbox OAuth

Project Setup

• Install PHP
• Install Composer
• Install Docker
  • For Mac: Docker Desktop | Orbstack
  • For Windows: Docker Desktop
  • For Linux: Docker Desktop
• Navigate to the project directory and run composer install
• Duplicate the .env.example: cp .env.example .env
• Configure alias for sail: alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
• Start the Docker containers: sail up -d
• Wait for the containers to start up. You can check the status of the containers with sail ps
• Generate a new APP_KEY: sail artisan key:generate. This will automatically update the .env file for the APP_KEY value.
• Create the database tables: sail artisan migrate
• Authorize Dropbox uploads by visiting http://localhost:8080/dropbox/authorize from the same machine, or your NAS HTTPS hostname for LAN use. DROPBOX_AUTH_PORT is published by Docker and reachable on your LAN unless your host firewall/network policy restricts it. Set the Dropbox app callback to the exact URI in DROPBOX_REDIRECT_URI and use https for any non-local callback.

Testing and Linting

• Run all checks: composer test
• Run formatting and lint checks: composer test:lint
• Run static analysis: composer test:types
• Run the test suite: composer test:unit
• If you are running commands inside Sail, use sail composer test, sail composer test:lint, sail composer test:types, and sail composer test:unit

Project reset

If you are stuck or Laravel is stuck.

• USE WITH CAUTION, THIS IS A HARD RESET OF THE DOCKER CONTAINERS: sail down -v --rmi all --remove-orphans
• Start the Docker containers: sail up -d
• Wait for the containers to start up. You can check the status of the containers witj sail ps
• Create the database tables: sail artisan migrate

Poll Neon

Clean-up and log monitoring

• Run bash reset-queue.sh which does the following:
  • Clear configs: sail artisan config:clear
  • Clear cache: sail artisan cache:clear
  • Clear routes: sail artisan route:clear
  • Regenerate autoloader files: sail composer dump-autoload
  • Flush the queue: sail artisan queue:flush
  • Clear the queue: sail artisan queue:clear
  • Restart the queue: sail artisan queue:restart
  • Clear the hash-table and failed jobs table:
    • Start MySQL terminal: sail artisan tinker
    • Clear hash-table: DB::table('neon_participant_hashes')->truncate();
    • Clear failed jobs-table: DB::table('failed_jobs')->truncate();
    • Exit MySQL terminal: exit
  • Reset the laravel log file (RHEL/Almalinux syntax): > storage/logs/laravel.log
  • Monitor the laravel log file (RHEL/Almalinux syntax): tail -f storage/logs/laravel.log

Start worker

• Start single-try worker (adjust --tries as needed): sail artisan queue:work --tries=1

Dropbox OAuth

• End-user setup walkthrough: see DROPBOX.md.
• The OAuth page is exposed on DROPBOX_AUTH_PORT and routes to the same Laravel app container, including access from other devices on your LAN.
• The Dropbox app callback should point to DROPBOX_REDIRECT_URI and must match the exact host, scheme, and port used by the browser. Use http only for localhost; use https with a LAN hostname for any non-local callback.
• After authorizing successfully, Laravel stores the Dropbox refresh_token and rotating access_token in the dropbox_tokens table.
• Dropbox access_token and refresh_token are encrypted at rest using Laravel encrypted casts (backed by APP_KEY).
• After rotating APP_KEY, rewrap existing Dropbox tokens using the previous key: sail artisan dropbox:rewrap-tokens --from-key="base64:OLD_APP_KEY_VALUE" --force.
• Reset local Dropbox auth state with sail artisan dropbox:reset-auth.
• To also clear local session state during account-switch testing, run sail artisan dropbox:reset-auth --with-sessions.
• Validate the integration with sail artisan dropbox:test-upload.
• Validate token refresh with sail artisan dropbox:test-upload --expire-token.
• Both validation commands upload a probe file into Dropbox under DROPBOX_UPLOAD_PATH/dropbox-test/ and remove their temporary local probe file afterward.
• Run the automated OAuth tests with sail artisan test tests/Feature/DropboxOAuthTest.php.

Re-authorization note

If you need to re-authorize (e.g. to rotate tokens or after revoking access in Dropbox), always initiate the flow from your APP_URL authorize endpoint (e.g. http://localhost:8080/dropbox/authorize for local development, or https://<NAS_HOSTNAME>/dropbox/authorize for LAN use) — do not reuse a stale Dropbox URL from a previous attempt.

If you log out of Dropbox first and then start a new flow, the Dropbox login page may appear to hang (spinner animation) after you submit your credentials. This is a known Dropbox SPA behavior: after a successful login, its client-side code tries to restore a cached "entry page" from a prior OAuth session and gets stuck when that cached URL is stale. Simply refresh the page — since you are now logged in, Dropbox will re-evaluate the OAuth URL and proceed directly to the consent screen. This only affects re-authorization in the same browser session; it does not affect end-user flows.

Poll Neon

• Poll neon with high verbosity (-vvv): sail artisan neon:poll-participants -vvv