Identity system setup improvements (#122)

Author: takemurahusky

.env.example

@@ -1,29 +1,33 @@
-APP_NAME=Laravel
+APP_NAME=Identity
 APP_ENV=local
-APP_KEY=
+# its better to generate a new key for every dev environment via `php artisan key:generate`, but just for simplicity I provided a default one
+APP_KEY=base64:xoIA1IBbUjD3w1PvYYjakHYrkH3lyHPgy4ctYvAiwAw=
 APP_DEBUG=true
-APP_URL=http://localhost
+APP_URL=http://identity.eurofurence.localhost/
+
+## secrets for hashids. you should generate your own via `openssl rand -hex 32` (or any other 32 random symbol string) for each of that
+HASHIDS_SALT=f9931717d231b7578668faedccce718c9cc9769af5fdf7ae1b8b3800241fc074
+HASHIDS_USER_SALT=5588ab6d9b4ffbaf4e21e93faf6feb612814364c093a56ad440e2df5816e3567
+HASHIDS_GROUP_SALT=20890ee95f76d3c8cb334359f2f9842d5fa31d4802e1f0e8dd033756017d979c
 
 LOG_CHANNEL=stack
 LOG_LEVEL=debug
 
 DB_CONNECTION=mysql
-DB_HOST=127.0.0.1
+DB_HOST=mysql
 DB_PORT=3306
 DB_DATABASE=laravel
-DB_USERNAME=root
-DB_PASSWORD=
+DB_USERNAME=sail
+DB_PASSWORD=password
 
 BROADCAST_DRIVER=log
-CACHE_DRIVER=file
+CACHE_DRIVER=redis
 FILESYSTEM_DRIVER=local
 QUEUE_CONNECTION=sync
 SESSION_DRIVER=database
 SESSION_LIFETIME=120
 
-MEMCACHED_HOST=127.0.0.1
-
-REDIS_HOST=127.0.0.1
+REDIS_HOST=redis
 REDIS_PASSWORD=null
 REDIS_PORT=6379
 
@@ -36,16 +40,49 @@ MAIL_ENCRYPTION=null
 MAIL_FROM_ADDRESS=null
 MAIL_FROM_NAME="${APP_NAME}"
 
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-AWS_DEFAULT_REGION=us-east-1
-AWS_BUCKET=
-AWS_USE_PATH_STYLE_ENDPOINT=false
+## AWS S3. doesnt need in local unlesss you want to test it
+#AWS_ACCESS_KEY_ID=
+#AWS_SECRET_ACCESS_KEY=
+#AWS_DEFAULT_REGION=us-east-1
+#AWS_BUCKET=
+#AWS_USE_PATH_STYLE_ENDPOINT=false
 
-PUSHER_APP_ID=
-PUSHER_APP_KEY=
-PUSHER_APP_SECRET=
+PUSHER_APP_ID=ef-identity
+PUSHER_APP_KEY=ef-identity
+PUSHER_APP_SECRET=some-default-secret-key-for-dev-environment
 PUSHER_APP_CLUSTER=mt1
 
+## Hydra settings. empty values will be filled on seding phase
+IDENTITY_OPENID_CONFIGURATION=http://identity.eurofurence.localhost/.well-known/openid-configuration
+HYDRA_ADMIN_URL=http://hydra:4445/
+# 64 symbols hex random string. for simplicity I provided a default one. you should generate a new one for every dev environment via `openssl rand -hex 32` and paste it here
+HYDRA_SECRET_KEY=2f8a4f1ad33752b26891beb16ea52640aa080142e77cf2fcd26af08fa25201d3
+
+IDENTITY_PORTAL_CALLBACK_URL=http://identity.eurofurence.localhost/auth/portal/callback
+IDENTITY_PORTAL_ID=
+IDENTITY_PORTAL_SECRET=
+
+IDENTITY_ADMIN_CALLBACK_URL=http://identity.eurofurence.localhost/auth/admin/callback
+IDENTITY_ADMIN_ID=
+IDENTITY_ADMIN_SECRET=
+
+IDENTITY_STAFF_CALLBACK_URL=http://identity.eurofurence.localhost/auth/staff/callback
+IDENTITY_STAFF_ID=
+IDENTITY_STAFF_SECRET=
+
+## sail settings (check out ./infra/dev/image/entrypoint.sh)
+#WWWUSER=1000
+#WWWGROUP=1000
+#WWWUSERNAME=sail
+## default command to run dev server
+#DEV_SERVER_COMMAND="php -d variables_order=EGPCS /var/www/html/artisan serve --host=0.0.0.0 --port=80"
+## you can noop it with
+#DEV_SERVER_COMMAND="fail -F /dev/null"
+## if your dev server is handling requests slow, you can run a octane server instead (does not work for now)
+#DEV_SERVER_COMMAND="php artisan octane:start --host=0.0.0.0 --port=80 --watch"
+## admin password. used once on database seeding phase
+ADMIN_PASSWORD=admin
+
+## values that will be forwarded to the frontend
 MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
 MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

README.md

@@ -3,17 +3,104 @@
 This is a Laravel, IntertiaJS with Vue based application that works as an OIDC Provider.
 
 ## Installation
-This project uses [laravel sail](https://laravel.com/docs/11.x/sail) for local development.
+
+You need to have at least docker and docker-compose installed.
+Podman is also supported, but you need to set up the podman socket and command to be compatible with docker.
 
 1. Clone the Repo
-2. Run `sail up -d` to start the docker containers.
-3. Run `sail artisan migrate`.
-4. Run `sail artisan db:seed`.
-5. Run `sail npm install`.
-6. Run `sail npm run dev`.
-7. Add `auth.eurofurence.localhost` and `identity.eurofurence.localhost` to your hosts file and forward them to `127.0.0.1`.
-8. You can now go to http://identity.eurofurence.localhost.
-
-### Security
+2. Copy `.env.example` to `.env` and set up the environment variables if needed.  
+   `cp .env.example .env`  
+   (you should generate new secret keys, but for simplicity some default ones are provided)
+3. Run `docker compose up -d` to start the docker containers.  
+   It may take a while to pull and build images for the first time.
+4. Wait when php dependencies are installed and the dev server starts.  
+   It may also take a while depending on your internet connection and computer performance.    
+   You can check the logs with `docker compose logs -f laravel.test`
+   (`Ctrl+C` here will close logs, but will keep the server running).
+5. Setup alias for sail:
+   ```bash
+   alias sail='./vendor/bin/sail'
+   ```
+   or use docker-compose directly:
+   ```bash
+   docker compose exec -it -u sail laravel.test <command>
+   ```
+   (further commands will have a sail and pure docker-compose version)
+6. Run `sail artisan migrate` or `docker compose exec -it -u sail laravel.test php artisan migrate`.
+7. Run `sail artisan db:seed` or `docker compose exec -it -u sail laravel.test php artisan db:seed`.
+8. Run `sail npm install` or `docker compose exec -it -u sail laravel.test npm install`.
+9. Run `sail npm run dev` or `docker compose exec -it -u sail laravel.test npm run dev`.  
+   (you can run this command locally. it may speed up HMR and file watching on some systems)
+10. Add `identity.eurofurence.localhost` to your hosts file and forward them to `127.0.0.1`.
+11. You can now go to http://identity.eurofurence.localhost.    
+    it may take a while to load first time.  
+    Default credentials are: `identity@eurofurence.localhost`, `admin` (unless you changed them in `.env`).
+
+### Entering laravel container
+
+To enter the laravel container, run `sail shell` or `docker compose exec -it -u sail laravel.test bash`.
+
+### Updating dev environment
+
+To keep your dev environment up to date after merging changes from the main branch or creating a new one, run:
+
+* `sail up -d` or `docker compose up -d` to update container image versions.
+* `sail npm install` or `docker compose exec -it -u sail laravel.test npm install` to update npm packages.
+* `sail composer install` or `docker compose exec -it -u sail laravel.test composer install` to update composer files.
+* `sail restart` or `docker compose restart` to restart the containers.
+
+### Stopping dev environment
+
+To stop the dev environment, run `sail stop` or `docker compose stop`.
+
+This action will stop all containers, free up the ports and keep data in containers and volumes.
+
+To start it again, run `sail up -d` or `docker compose up -d`.
+
+### Removing and cleaning up the dev environment
+
+**WARNING: This action will remove all containers and volumes, including the database and all data in it.**
+
+To remove the dev environment, run `sail down -v` or `docker compose down -v`.
+
+Also, you may want to remove `vendor` and `node_modules` if you want to perform
+a clean installation later `rm -rf vendor node_modules`.
+
+**WARNING: next step will remove all pulled and built images, build caches, volumes, networks and stopped containers.**
+
+For some rare cases, you may want to remove all pulled images and volumes `docker system prune -af`.
+
+## Exposed Ports
+
+* `:80` - HTTP terafic internal router. It routes http request to laravel container (mostly)
+  and hydra (`/.well-known`,`/oauth2`,`/health`,`/userinfo`)
+* `:8080` - traefic dashboard (for debugging)
+* `:3306` - MySQL database (can be changed via `FORWARD_DB_PORT` in `.env`)
+* `:4444`, `:4445`, `:5555` - Hydra endpoints (for debugging)
+* `:6379` - Redis (can be changed via `FORWARD_REDIS_PORT` in `.env`)
+* `:6001`, `:9601` - Soketi (local WS pusher implementation)
+  (can be changed via `PUSHER_PORT` and `PUSHER_METRICS_PORT` in `.env`)
+* `:7700` - MeiliSearch (can be changed via `FORWARD_MEILISEARCH_PORT` in `.env`)
+* `:1025`, `:8025` - MailPit local SMTP server
+  (can be changed via `FORWARD_MAILPIT_PORT`, `FORWARD_MAILPIT_DASHBOARD_PORT` in `.env`)
+
+## Connecting to the MySQL database from the host
+
+After you finish the installation, you can connect to the MySQL database from your host machine.
+
+* Host: `127.0.0.1`
+* Port: `3306` (or the port you set in `.env` for `FORWARD_DB_PORT`)
+* Username: `sail` (or the user you set in `.env` for `DB_USERNAME`)
+* Password: `password` (or the password you set in `.env` for `DB_PASSWORD`)
+* Database: `laravel` (or the database you set in `.env` for `DB_DATABASE`)
+
+## Receiving mail
+
+During development, you should use `identity.eurofurence.localhost` hostname
+(eg `some-user@identity.eurofurence.localhost`) to receive emails.
+
+Use mailpit to check the emails at [http://localhost:8025](http://localhost:8025).
+
+## Security
 
 If you discover any security related issues, please email me@thiritin.com instead of using the issue tracker.

database/seeders/UserSeeder.php

@@ -27,7 +27,7 @@ public function run()
             'name' => 'Admin',
             'email' => 'identity@eurofurence.localhost',
             'email_verified_at' => now(),
-            'password' => \Hash::make(random_bytes(32)),
+            'password' => \Hash::make(env('ADMIN_PASSWORD', random_bytes(32))),
         ]);
         // Warning this user will be made admin!
         $user->roles()->attach(Role::where('name', 'superadmin')->firstOrFail());