99 lines
2.6 KiB
Markdown
99 lines
2.6 KiB
Markdown
# E-Waste Backend
|
|
|
|
## Installation
|
|
|
|
Clone the repo.
|
|
|
|
### 1a. Laravel Sail / Docker (Recommended)
|
|
|
|
It's recommended to use Docker to set up the development environment. It's literally one command:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
alias sail='./vendor/bin/sail '
|
|
```
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
composer install
|
|
```
|
|
|
|
Don't use the `sail` prefix if you install it this way.
|
|
|
|
### 2. Migrations
|
|
|
|
Apply all migrations to the database:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sail php artisan key:generate
|
|
```
|
|
|
|
## Development
|
|
|
|
|
|
### Dev Server
|
|
|
|
Start the Laravel dev server with this command:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`
|