Add dashboard preview to README

README.md

@@ -19,6 +19,10 @@ It uses [Oxidized 0.37.0](https://github.com/ytti/oxidized) as its unmodified
 collection engine and adds inventory, authentication, audit logs, permanent Git
 history, notifications, and encrypted redundancy.
 
+<p align="center">
+  <img src="docs/assets/netkeep-dashboard-preview.webp" alt="NetKeep dashboard in dark mode with fictional example network data" width="1200">
+</p>
+
 > [!IMPORTANT]
 > In safe mode, NetKeep collects, compares, and exports configurations without
 > applying changes to equipment. This guarantee is conditional on reviewed

config/netkeep.php

@@ -8,6 +8,9 @@
 
     'version' => env('NETKEEP_VERSION', 'dev'),
     'source_url' => env('NETKEEP_SOURCE_URL', 'https://github.com/lrqnet/NetKeep'),
+    'readme_preview' => [
+        'password' => env('NETKEEP_README_DEMO_PASSWORD'),
+    ],
     'oxidized' => [
         'url' => env('OXIDIZED_URL', 'http://oxidized:8888'),
         'token' => env('OXIDIZED_INTERNAL_TOKEN'),

database/seeders/ReadmeDashboardSeeder.php

@@ -0,0 +1,149 @@
+<?php
+
+namespace Database\Seeders;
+
+use App\Enums\DeviceApprovalStatus;
+use App\Enums\DeviceStatus;
+use App\Enums\UserRole;
+use App\Models\BackupRun;
+use App\Models\Device;
+use App\Models\DeviceGroup;
+use App\Models\Organization;
+use App\Models\Site;
+use App\Models\User;
+use App\Services\DeviceApprovalService;
+use Illuminate\Database\Seeder;
+use Illuminate\Support\Facades\Hash;
+use RuntimeException;
+
+class ReadmeDashboardSeeder extends Seeder
+{
+    public function run(): void
+    {
+        $password = (string) config('netkeep.readme_preview.password');
+
+        if ($password === '') {
+            throw new RuntimeException('NETKEEP_README_DEMO_PASSWORD is required.');
+        }
+
+        $owner = User::query()->updateOrCreate(
+            ['email' => 'dashboard@example.test'],
+            [
+                'name' => 'Documentation Owner',
+                'password' => Hash::make($password),
+                'role' => UserRole::Owner,
+                'locale' => 'en',
+                'is_active' => true,
+                'email_verified_at' => now(),
+            ],
+        );
+
+        Organization::query()->updateOrCreate(
+            ['slug' => 'example-network-operations'],
+            [
+                'name' => 'Example Network Operations',
+                'locale' => 'en',
+                'timezone' => 'UTC',
+                'settings' => [
+                    'default_backup_interval' => 3600,
+                    'default_timeout' => 20,
+                    'full_backup_retention_days' => 30,
+                ],
+                'setup_completed_at' => now(),
+            ],
+        );
+
+        $core = DeviceGroup::query()->updateOrCreate(
+            ['name' => 'core'],
+            ['description' => 'Example core network devices'],
+        );
+        $edge = DeviceGroup::query()->updateOrCreate(
+            ['name' => 'edge'],
+            ['description' => 'Example edge network devices'],
+        );
+        $primary = Site::query()->updateOrCreate(
+            ['name' => 'Example Datacenter One'],
+            ['location' => 'Example City'],
+        );
+        $secondary = Site::query()->updateOrCreate(
+            ['name' => 'Example Branch West'],
+            ['location' => 'Example Region'],
+        );
+
+        $this->seedDevice($owner, $primary, $core, 'Example-Core-01', '192.0.2.10', 'ios', DeviceStatus::Healthy, 12);
+        $this->seedDevice($owner, $primary, $core, 'Example-Core-02', '192.0.2.11', 'junos', DeviceStatus::Healthy, 18);
+        $this->seedDevice($owner, $secondary, $edge, 'Example-Edge-01', '192.0.2.12', 'routeros', DeviceStatus::Healthy, 24);
+        $this->seedDevice($owner, $secondary, $edge, 'Example-Edge-02', '192.0.2.13', 'routeros', DeviceStatus::Healthy, 31);
+        $this->seedDevice($owner, $primary, $core, 'Example-Firewall-01', '192.0.2.14', 'fortios', DeviceStatus::Healthy, 42);
+        $this->seedDevice($owner, $secondary, $edge, 'Example-Access-01', '192.0.2.15', 'iosxe', DeviceStatus::Healthy, 55);
+        $this->seedDevice($owner, $secondary, $edge, 'Example-Edge-03', '192.0.2.16', 'routeros', DeviceStatus::Failing, 125);
+        $this->seedDevice($owner, $primary, $edge, 'Example-Access-02', '192.0.2.17', 'ios', DeviceStatus::Pending, 30);
+
+        Device::query()
+            ->whereIn('name', [
+                'Example-Core-01',
+                'Example-Core-02',
+                'Example-Edge-01',
+                'Example-Firewall-01',
+                'Example-Access-01',
+            ])
+            ->get()
+            ->each(function (Device $device): void {
+                BackupRun::query()->updateOrCreate(
+                    [
+                        'device_id' => $device->id,
+                        'git_commit' => str_pad((string) $device->id, 40, '0', STR_PAD_LEFT),
+                    ],
+                    [
+                        'status' => 'success',
+                        'started_at' => now()->subMinutes(20),
+                        'finished_at' => now()->subMinutes(10),
+                        'changed' => true,
+                    ],
+                );
+            });
+    }
+
+    private function seedDevice(
+        User $owner,
+        Site $site,
+        DeviceGroup $group,
+        string $name,
+        string $address,
+        string $model,
+        DeviceStatus $status,
+        int $minutesAgo,
+    ): void {
+        $device = Device::query()->updateOrCreate(
+            ['name' => $name],
+            [
+                'ip_address' => $address,
+                'port' => 22,
+                'transport' => 'ssh',
+                'oxidized_model' => $model,
+                'site_id' => $site->id,
+                'device_group_id' => $group->id,
+                'backup_interval' => 3600,
+                'timeout' => 20,
+                'enabled' => true,
+                'status' => $status,
+                'approval_status' => DeviceApprovalStatus::Approved,
+                'approved_by' => $owner->id,
+                'approved_at' => now()->subDays(7),
+                'approved_resolved_addresses' => [$address],
+                'ssh_host_key' => 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDocumentationOnlyKey',
+                'ssh_host_key_fingerprint' => 'SHA256:documentation-only-key',
+                'last_backup_at' => now()->subMinutes($minutesAgo),
+                'last_success_at' => $status === DeviceStatus::Healthy
+                    ? now()->subMinutes($minutesAgo)
+                    : null,
+                'next_collection_at' => now()->addDay(),
+                'consecutive_failures' => $status === DeviceStatus::Failing ? 1 : 0,
+            ],
+        );
+
+        $device->update([
+            'approval_fingerprint' => app(DeviceApprovalService::class)->fingerprint($device),
+        ]);
+    }
+}

tests/Feature/ReadmeDashboardSeederTest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Enums\DeviceApprovalStatus;
+use App\Models\BackupRun;
+use App\Models\Device;
+use App\Models\User;
+use Database\Seeders\ReadmeDashboardSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use RuntimeException;
+use Tests\TestCase;
+
+class ReadmeDashboardSeederTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_it_requires_an_explicit_demo_password(): void
+    {
+        config()->set('netkeep.readme_preview.password', null);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('NETKEEP_README_DEMO_PASSWORD is required.');
+
+        $this->seed(ReadmeDashboardSeeder::class);
+    }
+
+    public function test_it_seeds_only_fictional_dashboard_data(): void
+    {
+        config()->set('netkeep.readme_preview.password', 'documentation-demo-password');
+
+        $this->seed(ReadmeDashboardSeeder::class);
+
+        $this->assertDatabaseCount('devices', 8);
+        $this->assertDatabaseCount('backup_runs', 5);
+        $this->assertDatabaseHas('organizations', [
+            'slug' => 'example-network-operations',
+        ]);
+        $this->assertDatabaseHas('users', [
+            'email' => 'dashboard@example.test',
+        ]);
+        $this->assertSame(0, Device::query()
+            ->whereNot('ip_address', 'like', '192.0.2.%')
+            ->count());
+        $this->assertSame(8, Device::query()
+            ->where('approval_status', DeviceApprovalStatus::Approved)
+            ->where('enabled', true)
+            ->count());
+        $this->assertSame(1, User::query()
+            ->where('email', 'dashboard@example.test')
+            ->count());
+        $this->assertSame(5, BackupRun::query()->count());
+    }
+}