diff --git a/README.md b/README.md index 40a7e51..7628098 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,18 @@ ## Installation -Clone the repo. +Clone the repo, and copy the `.env.example` file to `.env`. ### 1a. Laravel Sail / Docker (Recommended) -It's recommended to use Docker to set up the development environment. It's literally one command: +It's recommended to use Docker to set up the development environment, so you don't need PHP or Composer on your system. Run this for the first-time setup: ```bash -docker compose up -d +docker run --rm \ + -v $(pwd):/var/www/html \ + -w /var/www/html \ + laravelsail/php84-composer:latest \ + bash -c "composer install --ignore-platform-reqs && php artisan sail:install --with=pgsql" ``` 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: @@ -18,6 +22,12 @@ From this point onward, run all shell commands with the `./vendor/bin/sail` pref alias sail='./vendor/bin/sail ' ``` +Then, it's just one command every time you want to spin up your development environment: + +```bash +sail up -d +``` + ### 1b. Manual Alternatively, you can install PHP 8 (with the [relevant extensions](https://stackoverflow.com/questions/40815984/how-to-install-all-required-php-extensions-for-laravel)), PHP Composer, and Postgres on your system, then go into this directory and run: @@ -40,7 +50,7 @@ sail php artisan migrate ### 3. Generate key -Copy the `.env.example` file to `.env`. Generate the application encryption key: +Generate the application encryption key: ```bash sail php artisan key:generate @@ -54,22 +64,40 @@ sail php artisan key:generate Start the Laravel dev server with this command: ```bash -sail php artisan serve --host=0.0.0.0 +sail php artisan serve ``` 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): +### Create Model ```bash -docker compose restart +sail php artisan make:model ``` +Check out the flags you can pass into this command first, since it can save you from writing boilerplate (controllers, factories, migrations, tests, etc). + +### PHP Console + +```bash +sail php artisan tinker +``` + +Really useful for doing database operations and such by interacting with model objects (no SQL required). + +### Rebuilding Sail Containers + +Only do this if you totally break something in the container or need a fresh start after changing something in compose.yaml. It may take a while. + +```bash +sail build --no-cache +``` + +For troubleshooting purposes, note that the containers still can access real paths on your system (like PHP packages going in `./vendor`, Postgres databases in the `sail-pgsql` volume), so you may want to try clearing those first. + ## 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. +You should install an HTTP request client like Insomnia. Make sure you are setting the `Accept: application/json` and `Referer: http://localhost` headers in all requests -- this application is not designed to generate any HTML views, aside from email messages and the password reset page. (The Insomnia project already does this.) ### List all Routes @@ -83,7 +111,7 @@ Authentication is handled by Laravel Sanctum and Laravel Fortify. Instead of usi #### 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 `=`). +`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 URL-decode it first (basically, if there's a `%3D` at the end, change it to `=`). The Insomnia project takes care of this for you, as long as you hit run in the first place. #### Fortify Routes