From this point onward, run all shell commands with the ./vendor/bin/sail prefix so they get run inside the container. You might want to set up a shell alias in ~/.bashrc to remove the relative path:

alias sail='./vendor/bin/sail '

1b. Manual

Alternatively, you can install PHP 8 (with the relevant extensions), PHP Composer, and Postgres on your system, then go into this directory and run:

composer install

Don't use the sail prefix if you install it this way.

2. Migrations

Apply all migrations to the database:

sail php artisan migrate

Note: this step has to be redone every time a new database migration is written.

3. Generate key

Copy the .env.example file to .env. Generate the application encryption key:

sail php artisan key:generate

Development

Dev Server

Start the Laravel dev server with this command:

sail php artisan serve --host=0.0.0.0

Then you can go to http://localhost/ in your browser (if using Sail) or http://localhost:8000/ (for manual installs). The site will live update any time you make changes.

Changing Docker Configs

If you change the compose.yml file, run this in your shell (not with Sail):

docker compose restart

Testing

You should install an HTTP request client like Postman or Insomnia. Make sure you are setting the Accept: application/json header in all requests -- this application is not designed to generate any HTML views, aside from email messages and the password reset page.

List all Routes

sail php artisan route:list

Authenticating

Authentication is handled by Laravel Sanctum and Laravel Fortify. Instead of using JWTs or non-expiring API tokens, which come with a host of security issues, we use good old fashioned cookies to maintain the logged-in user's session.

Sanctum Routes

GET /sanctum/csrf-cookie: must be ran first to get the XSRF-TOKEN cookie. Then, the client is responsible for pasting this token into the X-XSRF-TOKEN request header of all subsequent authenticated requests. Make sure to base64-decode it first (basically, if there's a %3D at the end, change it to =).

Fortify Routes

POST /login

POST /register

POST /logout

Application Routes

GET /api/user