Setup

This page documents the initial setup required for a new installation of this application (whether for production or development use).

Requirements

• PHP 8.1
  • Extensions needed: gd, intl, mbstring, pgsql, xml
  • Ubuntu: apt install php8.1 php8.1-gd php8.1-intl php8.1-mbstring php8.1-pgsql php8.1-xml
• Composer
  • Ideally should be named composer and located somewhere in your PATH (i.e. /usr/local/bin/composer)
• Node.js
  • On Ubuntu, I installed the LTS release from NodeSource to get a new enough version.
• NPM (sometimes included with Node.js)
• Yarn (npm install -g yarn)
• poppler-utils (apt install poppler-utils)
• Symfony CLI
• PostgreSQL server

Environment

On my development machine, I have a .env.local file in the repository that looks like this:

S3_STORAGE_KEY="keygoeshere"
S3_STORAGE_SECRET="secretgoeshere"
S3_PREFIX=dev-yournamehere/

In production, the .env.local file looks more like this:

APP_ENV=prod
APP_SECRET=secretgoeshere
DATABASE_URL="postgresql://user:[email protected]:5432/sportsarchive?serverVersion=13&charset=utf8"
S3_STORAGE_KEY="keygoeshere"
S3_STORAGE_SECRET="secretgoeshere"
S3_PREFIX=prod/

Database

You need a local Postgres server. If your server is running at 127.0.0.1:5432 with username/password is postgres/postgres, you don't need to set the database details. Otherwise, you'll need to add this line to your .env.local file:

DATABASE_URL="postgresql://user:[email protected]:5432/sportsarchive?serverVersion=13&charset=utf8"

You'll then need to set up the database with these commands:

• symfony console doctrine:database:create (creates the database)
• symfony console doctrine:migrations:migrate (apply database schema)
• symfony console doctrine:query:sql "CREATE EXTENSION unaccent;" (enable unaccent module)

Messenger

This project uses a constantly running worker to perform background tasks (namely, deriving assets from PDFs so that the BookReader plugin can work). On initial install, you'll need to set up the database table that task messages are stored in with this command: symfony console messenger:setup-transports.

Once your instance of the site is up, you'll need to run one or more workers via the messenger:consume command. For development work, the Symfony CLI tool can automatically start a worker; see Development commands#Dev server for more info. For production use, a good way to keep workers running is with systemd; see Building#Messenger service for more details.

For local development

These steps are only necessary for local development, and not for production building.

Symfony CLI

The Symfony command-line tool should be installed in all environments so that you can use symfony php and symfony console to run PHP with the correct php.ini. The command-line tool is especially useful in local development for running a test server.

You will likely also want to set up a local certificate authority so that you don't have HTTPS errors in your browser when using the Symfony dev server. This can be done by running symfony server:ca:install.

Pre-commit hook

Before committing, all tests and checks should be run. In order to enforce this, the bin/pre-commit.sh should be run as a pre-commit hook. Create the following file at .git/hooks/pre-commit:

#!/usr/bin/env bash
bin/pre-commit.sh

Then make it executable with chmod +x .git/hooks/pre-commit.

What's next?

Once you have completed all the setup steps on this page, you will be most of the way there. For local development work, find next steps at Development commands. For production use, find next steps at Building.