Skip to content

Setup (Manual)

Jump to bottom
github-actions[bot] edited this page Jan 7, 2025 · 6 revisions

While the Docker containers are generally easier to setup and use, manual setup of Tracker isn't terribly complex either. This gives you the most control over every aspect of the setup and lets you interact directly with the system without any layers of abstraction that some may find undesireable. You'll also be able to run Tracker on a traditional shared web host this way.

Requirements

  • A web server, such as Nginx or Apache
  • PostgreSQL, MariaDB, or MySQL (8.0+) server as a database
  • (recommended) Redis, Memcached, or another Laravel-compatible key/value store for caching data
  • PHP 8.2+ with the following extensions:
    • PDO + your database extension of choice
    • openssl
    • ctype
    • filter
    • hash
    • mbstring
    • session
    • tokenizer
    • ZIP
    • GD
  • Composer to install backend dependencies
  • Node.js & NPM to install frontend dependencies
  • Your event's instance of ConCat to allow volunteers and staff to authenticate with the system
    • All users log in to the application using ConCat with OAuth.
    • You will need Developer access to your event's ConCat instance to create the OAuth app. Specifically, you will need the oauth:manage permission to set everything up. Alternatively, have someone else create an OAuth app in ConCat for you and have them provide you with the client ID and secret.
    • The OAuth app will require the volunteer:read and registration:read application permissions for OAuth Bearer tokens, which are used for generating the Volunteer Applications reports and retrieving badge details inside Tracker.

Installation

  1. Clone this repository in your web server's document root (or download a tarball and extract it to it).
  2. Run composer install --no-dev --classmap-authoritative to download all production backend dependencies and optimize the autoloader automatically.
  3. Run npm install to download all frontend dependencies.
  4. Run npm run build to bundle and optimize the frontend assets.
  5. Copy .env.example to .env and update the values appropriately.
  6. Run php artisan key:generate to generate an encryption key and automatically fill in the APP_KEY value in .env. This key should be kept the same between all instances of Tracker connected to the same environment (production, QA, etc.) and should only be regenerated when absolutely necessary (compromise, improved algorithm). Regenerating or using a different key will result in any encrypted (not hashed!) values in the database or cache becoming unreadable.
  7. Run php artisan migrate to run all migrations on the database.
  8. Log in to the application in your web browser via the OAuth flow to make sure a user gets created for you.
  9. Run php artisan auth:set-role to set your user's role to admin.
  10. Run php artisan telegram:set-commands to send the list of bot commands to Telegram.
  11. Run php artisan telegram:set-webhook to inform Telegram of the bot's webhook URL.
  12. Add a cron entry to run php artisan schedule:run every minute so that reward notifications can be triggered and ongoing shifts automatically stopped at the configured day boundary.
    • Example crontab entry: * * * * * cd /var/www/html && /usr/local/bin/php artisan schedule:run >> /dev/null 2>&1'
  13. Run php artisan queue:work in a separate process (using supervisor or something similar) to process queue entries as they come in. You can have multiple of these running at once if the queue becomes backed up.
  14. To greatly improve boot performance of the application on each hit, run the following:
    • php artisan config:cache to cache the fully-resolved configuration to a file
    • php artisan route:cache to cache the routes to a file
    • php artisan event:cache to cache the auto-discovered event listeners to a file
    • php artisan view:cache to pre-compile and cache all of the Blade templates

Updating

  1. Run php artisan down to put the application in maintenance mode.
  2. Pull or upload the current version of the code from this repository.
  3. Run composer install --no-dev --classmap-authoritative to download any new production backend dependencies and optimize the autoloader automatically.
  4. Run npm install to download any new frontend dependencies.
  5. Run npm run build to bundle and optimize the frontend assets.
  6. Run php artisan migrate to run any new migrations on the database.
  7. Run php artisan telegram:set-commands to send the list of bot commands to Telegram.
  8. Run php artisan telegram:set-webhook to inform Telegram of the bot's webhook URL.
  9. Restart any queue workers you have running (php artisan queue:work) in separate processes to ensure they're using the latest code.
  10. To greatly improve boot performance of the application on each hit, run the following:
    • php artisan config:cache to cache the fully-resolved configuration to a file
    • php artisan route:cache to cache the routes to a file
    • php artisan event:cache to cache the auto-discovered event listeners to a file
    • php artisan view:cache to pre-compile and cache all of the Blade templates
  11. Run php artisan up to pull the application out of maintenance mode.
Clone this wiki locally