feat: make name unique & email optional for users who don't want to log in + release: v1.3.0

Author: lchristmann

DEVELOPER-DOCS.md

@@ -16,6 +16,7 @@ The past development is documented in the [4_IMPLEMENTATION.md](docs/4_IMPLEMENT
 - [Prerequisites](#prerequisites)
 - [Commands for Everyday Development](#commands-for-everyday-development)
 - [Setting Up the Development Environment](#setting-up-the-development-environment)
+- [Seeding Production](#seeding-production)
 - [Usage](#usage)
   - [Accessing the Workspace Container](#accessing-the-workspace-container)
   - [Run Artisan Commands:](#run-artisan-commands)
@@ -123,6 +124,90 @@ npm run dev
 
 Open your browser and navigate to [http://localhost](http://localhost).
 
+## Seeding Production
+
+Seeding production isn't as easy as running `docker compose exec php-fpm php artisan db:seed --force` on the server [as in the Laravel docs](https://laravel.com/docs/12.x/seeding#forcing-seeding-production).
+
+That's because neither `fakerphp/faker` (the dev dependency most crucial to seeding) nor `composer` itself is included in the `production` Docker image (see the [docker/deployment/php-fpm/Dockerfile](docker/deployment/php-fpm/Dockerfile) -> only the production dependencies get copied from a previous builder stage to the production stage).
+
+Thus, The easiest way to seed production like development here, is exporting the data from the development Postgres database, getting the exported data to the server and importing it there.
+
+> **Warning:** Do this production seeding just for demonstration purposes and delete all that data before serious usage.<br>
+> The seeded admin user's credentials are publicly visible in this project's [DatabaseSeeder.php](database/seeders/DatabaseSeeder.php) and all other users have the password `password`.
+
+1. Run the waffle-dashboard as described in the [Commands for Everyday Development](#commands-for-everyday-development) section.
+2. Export the data from the two main database tables
+```shell
+docker compose -f compose.dev.yaml exec postgres bash
+\copy users TO '/tmp/users.csv' CSV HEADER;
+\copy waffle_eatings TO '/tmp/waffle_eatings.csv' CSV HEADER;
+exit
+exit
+```
+3. Copy the CSV files from the Postgres container to your local host machine
+```shell
+docker cp waffle-dashboard-postgres-1:/tmp/users.csv ./users.csv
+docker cp waffle-dashboard-postgres-1:/tmp/waffle_eatings.csv ./waffle_eatings.csv
+```
+4. Transfer it from your local host machine to the server
+```shell
+scp users.csv waffle_eatings.csv root@lchristmann-1:/opt/waffle-dashboard
+```
+> Given I have below SSH config in my `~/.ssh/config` file
+> 
+> ```
+> Host lchristmann-1
+> HostName yourServersIPAddressHere
+> User root
+> IdentityFile ~/.ssh/lchristmann-1
+> ```
+5. SSH into the server and `cd` into the waffle-dashboard's directory
+```shell
+ssh lchristmann-1
+cd /opt/waffle-dashboard
+```
+6. Copy the CSV files from the server to the Postgres container
+```shell
+docker cp users.csv waffle-dashboard-postgres-1:/tmp/users.csv
+docker cp waffle_eatings.csv waffle-dashboard-postgres-1:/tmp/waffle_eatings.csv
+```
+7. Backup the data from the users table
+```shell
+docker compose exec -T postgres psql -U laravel -d app -c "\
+COPY (SELECT name, email, email_verified_at, password, is_admin, remember_token, created_at, updated_at FROM users) \
+TO STDOUT WITH CSV HEADER" > users_data.csv
+```
+8. Delete all data from the `users` and `waffle_eatings` tables (else we'd run into conflicts trying to insert records with already existing `id` values)
+```shell
+docker compose exec postgres psql -d app -U laravel
+TRUNCATE TABLE waffle_eatings, users RESTART IDENTITY;
+```
+9. Import the seeding data to the server's Postgres database
+```postgresql
+\copy users FROM '/tmp/users.csv' DELIMITER ',' CSV HEADER;
+\copy waffle_eatings FROM '/tmp/waffle_eatings.csv' DELIMITER ',' CSV HEADER;
+SELECT setval(pg_get_serial_sequence('users','id'), (SELECT MAX(id) FROM users));
+SELECT setval(pg_get_serial_sequence('waffle_eatings','id'), (SELECT MAX(id) FROM waffle_eatings));
+```
+```shell
+exit
+```
+10. Restore the previously present users data
+```shell
+docker compose exec -T postgres psql -U laravel -d app -c "\
+COPY users(name, email, email_verified_at, password, is_admin, remember_token, created_at, updated_at) \
+FROM STDIN WITH CSV HEADER" < users_data.csv
+```
+
+Done - now you can log in for example with the admin user: `[email protected]` and `admin` or any other user with their email and password `password`.
+
+To clean up the temporary files, run below commands:
+
+```shell
+rm users.csv waffle_eatings.csv # in this project
+rm /opt/waffle-dashboard/users_data.csv /opt/waffle-dashboard/waffle_eatings.csv # on the server
+```
+
 ## Usage
 
 Here are some common commands and tips for using the development environment:

README.md

@@ -9,6 +9,8 @@ The Waffle Dashboard is a lightweight, self-hostable application for tracking an
 ![screenshot of the waffle dashboard](docs/screenshots/dashboard.png)
 _Check out the [docs/screenshots](docs/screenshots) folder._
 
+> Please star the repository if you find this project useful - it helps me understand how many people rely on it when making changes.
+
 ## Table of Contents <!-- omit in toc -->
 
 - [Get the Waffle Dashboard](#get-the-waffle-dashboard)

app/Filament/Actions/UserBulkCreateAction.php

@@ -8,6 +8,7 @@
 use Filament\Forms\Components\TextInput;
 use Filament\Forms\Components\Toggle;
 use Filament\Schemas\Components\Grid;
+use Filament\Schemas\Components\Utilities\Get;
 use Illuminate\Support\Facades\Hash;
 
 class UserBulkCreateAction extends Action
@@ -30,11 +31,17 @@ protected function setUp(): void
                     ->schema([
                         Grid::make()
                             ->schema([
-                                TextInput::make('name')->required()->maxLength(255),
-                                TextInput::make('email')->required()->email()->maxLength(255),
+                                TextInput::make('name')->unique()->required()->maxLength(255),
+                                TextInput::make('email')->unique()->email()->maxLength(255)
+                                    ->required(fn (Get $get): bool => filled($get('password')))
+                                    ->live(onBlur: true),
 
-                                TextInput::make('password')->password()->required()
-                                    ->dehydrateStateUsing(fn ($state) => $state ? Hash::make($state) : null),
+                                TextInput::make('password')
+                                    ->password()
+                                    ->required(fn (Get $get): bool => filled($get('email')))
+                                    ->dehydrateStateUsing(fn ($state) => $state ? Hash::make($state) : null)
+                                    ->dehydrated()
+                                    ->live(onBlur: true),
 
                                 Toggle::make('is_admin')->label('Admin')->inline(false),
                             ])
@@ -46,8 +53,8 @@ protected function setUp(): void
                 foreach ($data['users'] as $userData) {
                     User::create([
                         'name' => $userData['name'],
-                        'email' => $userData['email'],
-                        'password' => $userData['password'],
+                        'email' => $userData['email'] ?? null,
+                        'password' => $userData['password'] ?? null,
                         'is_admin' => $userData['is_admin'] ?? false,
                     ]);
                 }

app/Filament/Resources/Users/Schemas/UserForm.php

@@ -5,6 +5,7 @@
 use App\Models\User;
 use Filament\Forms\Components\TextInput;
 use Filament\Forms\Components\Toggle;
+use Filament\Schemas\Components\Utilities\Get;
 use Filament\Schemas\Schema;
 use Illuminate\Support\Facades\Hash;
 
@@ -14,14 +15,17 @@ public static function configure(Schema $schema): Schema
     {
         return $schema
             ->components([
-                TextInput::make('name')->required(fn (string $context) => $context === 'create')->maxLength(255),
-                TextInput::make('email')->required(fn (string $context) => $context === 'create')->email()->maxLength(255),
+                TextInput::make('name')->unique()->required()->maxLength(255),
+                TextInput::make('email')->unique()->email()->maxLength(255)
+                    ->required(fn (Get $get, string $context) => $context === 'create' && filled($get('password')))
+                    ->live(onBlur: true),
 
                 TextInput::make('password')
                     ->password()
-                    ->required(fn (string $context) => $context === 'create')
+                    ->required(fn (Get $get, string $context) => $context === 'create' && filled($get('email')))
                     ->dehydrateStateUsing(fn ($state) => $state ? Hash::make($state) : null)
-                    ->dehydrated(fn ($state) => filled($state)),
+                    ->dehydrated(fn ($state) => filled($state))
+                    ->live(onBlur: true),
 
                 Toggle::make('is_admin')->label('Admin')->inline(false)
                     ->disabled(fn (?User $record) => $record && $record->id === auth()->id())

database/migrations/0001_01_01_000000_create_users_table.php

@@ -13,15 +13,17 @@ public function up(): void
     {
         Schema::create('users', function (Blueprint $table) {
             $table->id();
-            $table->string('name');
-            $table->string('email')->unique();
+            $table->string('name')->unique();
+            $table->string('email')->nullable();
             $table->timestamp('email_verified_at')->nullable();
-            $table->string('password');
+            $table->string('password')->nullable();
             $table->boolean('is_admin')->default(false);
             $table->rememberToken();
             $table->timestamps();
         });
 
+        DB::statement('CREATE UNIQUE INDEX users_email_unique ON users (email) WHERE email IS NOT NULL;');
+
         Schema::create('password_reset_tokens', function (Blueprint $table) {
             $table->string('email')->primary();
             $table->string('token');

docker-compose.yaml

@@ -30,7 +30,7 @@ services:
 
   php-fpm:
     # For the php-fpm service, we will create a custom image to install the necessary PHP extensions and setup proper permissions.
-    image: leanderchristmann/waffle-dashboard:1.2.0
+    image: leanderchristmann/waffle-dashboard:1.3.0
     restart: unless-stopped
     volumes:
       # Mount persistent storage

docs/4_IMPLEMENTATION.md

@@ -341,3 +341,18 @@ On this occasion, I also optimized the Leaderboard page (now running one query f
 > Commits:
 >
 > - `bb786c22`: `docs: upload new screenshots`
+> - `4897c2db`: `release: v1.2.0`
+
+## 19. Further Improve the User Experience (UX) (`v1.3.0`)
+
+In practice, there'll be users, who don't manage their own waffle eatings entries, but let others enter them.<br>
+Hence the users bulk create would be too cumbersome, if it didn't allow creation just by name.
+
+Therefor we need the name to be unique. Email and password can be set (together, forming a pair of credentials), but don't have to.
+
+Extra: for showcasing purposes I added instructions on how to transfer seeding data into a production environment.
+
+Some helpful documentation pages:
+
+- https://filamentphp.com/docs/4.x/forms/overview#conditionally-making-a-field-required
+- https://stackoverflow.com/questions/8289100/create-unique-constraint-with-null-columns