Skip to Content

Wiki source code of 1st Run Checklist

Last modified by Robert Schaub on 2026/02/08 08:12
Hide last authors
Robert Schaub 1.1 1 = 1st Run Checklist =
2
3 == Purpose ==
4
5 This checklist is designed to ensure **POC1 runs end-to-end on the first attempt**. It focuses on the most common real-world failure points.
6
7 ----
8
9 == Phase 1 — Repository Setup ==
10
11 * Clone the Git repository
12 * Open:
13 ** API in Visual Studio 2022
14 ** Web app in Cursor or VS Code
15
16 **Hint:** Do not change configuration yet.
17
18 ----
19
20 == Phase 2 — Environment Configuration ==
21
22 === Web (apps/web) ===
23
24 * Copy .env.example → .env.local
25 * Set:
26 ** OPENAI_API_KEY
27 ** Verify FH_API_BASE_URL points to the local API
28
29 === API (apps/api) ===
30
31 * Copy appsettings.Development.example.json → appsettings.Development.json
32 * Verify:
33 ** Admin:Key matches FH_ADMIN_KEY
34 ** Runner:RunnerKey matches FH_INTERNAL_RUNNER_KEY
35 ** Db:Provider is set to sqlite
36
37 **Important Hint:**
38 Key mismatches are the most common cause of failure.
39
40 ----
41
42 == Phase 3 — Database Initialization ==
43
44 Run:
45
46 {{{cd apps/api
47 dotnet ef database update
48 }}}
49
50 Expected result:
51
52 * factharbor.db file is created
53 * No errors reported
54
55 ----
56
57 == Phase 4 — Start Services ==
58
59 Recommended:
60
61 {{{powershell -ExecutionPolicy Bypass -File scripts/first-run.ps1
62 }}}
63
64 This:
65
66 * installs dependencies
67 * applies migrations
68 * starts API
69 * starts Web UI
70
71 ----
72
73 == Phase 5 — Health Verification ==
74
75 Check:
76
77 * API: http:~/~/localhost:5000/health
78 * Web: http:~/~/localhost:3000/api/health
79
80 Expected:
81
82 * HTTP 200
83 * ok: true
84
85 Do not proceed until both are healthy.
86
87 ----
88
89 == Phase 6 — First Analysis ==
90
91 Steps:
92
93 1. Open the Web UI
94 1. Paste a short text (avoid URL first)
95 1. Click **Run Analysis**
96 1. Observe progress
97 1. Verify result is visible as:
98 1*. Report
99 1*. JSON
100
101 ----
102
103 == Common Failure Patterns ==
104
105 |=Symptom|=Likely Cause
106 |Job stuck in QUEUED|Runner key mismatch
107 |Job fails immediately|Missing OpenAI key
108 |No progress updates|Admin key mismatch
109 |API not starting|Database migrations missing
110
111 ----
112
113 == Definition of Success ==
114
115 * Analysis completes successfully
116 * Refreshing the job page still shows results
117 * /jobs lists previous runs
118
119 At this point, **POC1 is operational**.