NOSTR AFRICA · CUSTOMER GUIDE

Setting up AI Attendance at a new school

A practical, step-by-step guide to preparing, installing, piloting and running face-recognition attendance with the dashboard at attendance.nostr.africa.

attendance.nostr.africa · Updated October 2026

School administratorsPrincipals & teachersThe person installing it

How to use this guideRead sections 1–3 before buying or mounting anything. Follow section 4 on setup day. Keep sections 6 and 8 handy for staff, and print the checklist in section 10 for the go-live meeting. Words in purple bold are the exact labels you will see on screen.

1What the system does (and doesn't)

Cameras watch doorways and classrooms; the system recognises enrolled students' faces and records attendance automatically. Staff check and correct it on a web dashboard.

Dashboard: https://attendance.nostr.africa
Top menu: Live Events Reports Students Cameras Users Settings Audit Log out

What it does

✓ Recognises enrolled students from IP cameras or video files.
✓ Logs entry and exit times from Entrance/Exit cameras and works out dwell time (time on site).
✓ Shows a live view of recent events, camera status and a "present today" count.
✓ Lets staff mark students present/absent by hand, with a required note.
✓ Produces reports by class, student and date range — download as CSV or print / save as PDF.
✓ Keeps an audit log of logins, enrollments, corrections, exports and settings changes.
✓ Stores no video or camera frames.

What it doesn't do (yet)

✗ Exam invigilation / exam monitoring.
✗ Strong anti-spoofing: it only requires a face to match across several frames, so a printed photo may fool it.
✗ Restrict teachers to their own classes — teachers currently see all classes.
✗ Built-in PDF export (use the browser's print to PDF instead).
✗ Take enrollment photos straight from a camera — photos are uploaded.

How recognition works, in plain English

When you enroll a student, the system turns their photos into a face fingerprint — a list of 512 numbers. The photos themselves are then thrown away.
Each camera is checked about 5 times per second. Every face it finds is compared with the enrolled fingerprints.
A student is only logged when their face matches well (similarity of 0.45 or more) in 3 of the last 5 frames. This avoids one-off lucky or unlucky matches.
The same student is not logged again on the same camera for 5 minutes (the "cooldown"), so standing in a doorway doesn't create dozens of records.

Who can do what

Role	Can do
Admin	Everything, including cameras, users, settings and enrollment.
Principal	View, reports, and the audit log.
Teacher	View, reports, and manual corrections. (Not yet limited to their own classes.)

2Before you start

Face recognition handles sensitive personal data about children. Sort out these five things before a single camera is switched on.

Get consent from students and parents — this is required. Explain what is recorded (a face fingerprint, attendance times, optionally a small thumbnail), why, who can see it and how long it is kept. Keep a record of who has consented, and only enroll students who have.
Put up notice signs near every camera. Anyone walking past should know that face recognition is in use for attendance.
Decide how long to keep attendance data. The system automatically deletes events older than retention_days (default 365 days). Agree the right period with school leadership and set it on the Settings page.
Check your local data-protection law. Many countries have specific rules for biometric data and children's data. Confirm what applies to your school (for example registration, a responsible officer, or a written assessment) before going live.
Decide who will be admin. The admin can see and change everything. Keep it to one or two trusted people; everyone else gets a teacher or principal account.

WarningDo not enroll any student without consent, and do not rely on the system as a security barrier. It can be fooled by a printed photo and is designed for attendance, not access control.

TipUse the facts in section 7 (Privacy & data handling) as the basis for your parent letter — it lists exactly what is kept and what is not.

3Camera & network checklist

Good recognition is 80% camera placement and lighting. Walk through this list with your camera installer.

Requirement	Why / what to check
RTSP-capable IP cameras	The system reads camera streams over RTSP. Most Hikvision and Dahua IP cameras support this.
720p resolution or better	Faces need enough pixels to be recognised. (You will still connect the lower-resolution substream to save CPU — see step 4c.)
Entrance cameras at face / eye level	The camera should see faces straight on as students walk towards it — not the tops of heads from a high ceiling.
Good light on the front of faces	Faces must be lit from the front. Dim corridors cause missed students.
Avoid backlight	Don't point a camera at a bright doorway or window — faces turn into dark silhouettes.
Camera network reachable from the server	The server must be able to connect to each camera's IP address. Ask your installer/IT to confirm this.
RTSP username & password	Get these from the installer for every camera, together with its IP address.

Where to put cameras

Entrance — logs when a student arrives. Start here: one entrance camera is enough for a pilot.
Exit — logs when a student leaves. With both Entrance and Exit cameras you get entry time, exit time and dwell time.
Classroom — logs that a student was seen in that room.

TipA narrow doorway where students walk one or two at a time towards the camera works much better than a wide, crowded gate.

Server capacityThe current server (20 CPU cores, no GPU) handles about 5 frames per second per camera and uses about 2 CPU cores per active camera. That is fine for a pilot of about 2–4 cameras. See section 9 before going past about 6–8 cameras.

4Step-by-step setup

Follow steps a–g in order. Plan for one entrance camera and one pilot class first; add more once the pilot works well.

a · Log in, handle the admin account, delete demo data

Open https://attendance.nostr.africa in a web browser.
Log in with username admin. The admin password is kept by the system owner on the server — get it from them directly. There is no public signup.
Agree who holds the admin password and store it somewhere safe (for example a password manager). Don't share the admin login for daily use — create individual accounts in step b.
Go to Students. You will see a class called DEMO with 4 test people. Delete all four before going live.

WarningIf the DEMO people are left in, they will show up in your counts and reports. Removing them is on the go-live checklist.

b · Create staff accounts

Go to Users and find Add or update user.
Enter a username and password for the staff member.
Choose the role: teacher, principal or admin (see the table in section 1).
Click Save. To remove someone, use Delete.

TipGive every person their own account. The Audit page records who did what, which only helps if logins aren't shared.

c · Add the first entrance camera

Go to Cameras and find Add camera or video.
Name: something staff will recognise, e.g. "Main gate".
URL: the camera's RTSP address. Use the camera's lower-resolution substream to save CPU:
Brand RTSP URL (substream)
Hikvision rtsp://user:pass@IP:554/Streaming/Channels/102
Dahua rtsp://user:pass@IP:554/cam/realmonitor?channel=1&subtype=1
Replace user, pass and IP with the details from your installer.
Zone: choose Entrance (logs entry). Other options are Exit (logs exit) and Classroom.
Submit the form, then open Live. Check the new camera appears in camera status with an fps figure (frames per second, around 5). If it does, the system is receiving the video.

Brand	RTSP URL (substream)
Hikvision	`rtsp://user:pass@IP:554/Streaming/Channels/102`
Dahua	`rtsp://user:pass@IP:554/cam/realmonitor?channel=1&subtype=1`

Good to know

Camera passwords are hidden on the page once saved.
If a camera drops its connection, the system retries automatically.
Cameras can be switched on or off on the Cameras page — handy for holidays or maintenance.
No camera yet? A video file works too: put it in /home/jb/attendance/media/ on the server and enter /media/name.mp4 as the URL.

d · Enroll a pilot class

Go to Students and find Enroll a student.
Enter the student's name, student ID and class.
Upload 5–10 photos with only that student's face in each.
Submit the form. Photos with no face, or with several faces, are rejected with a message — replace them and try again.
Repeat for each student in the pilot class (only those with consent).

Photo tips — this matters most

5–10 photos per student, from slightly different angles (straight on, a little left, right, up, down).
Good, even light on the face; no strong shadows or bright window behind.
No hats or sunglasses; the full face visible.
Ideally taken at the camera's angle — e.g. standing where students walk past the entrance camera, at that height.
Only one face per photo; crop out friends in the background.

Adding more photos laterEnrolling again with the same student ID adds the new photos to the existing student instead of creating a duplicate. Photos are discarded after processing; only the face fingerprint (and optionally one small thumbnail) is kept.

e · Watch Live as students walk in

On the first pilot morning, open Live on a screen near the entrance (it refreshes every 5 seconds).
Watch recent events appear as students arrive, and the present today count go up.
Keep an eye on camera status: fps, faces seen and unknown faces. Lots of unknown faces from enrolled students means photos or camera position need work (section 5).
Note any student who walked in but wasn't logged — you will fix them in the next step.

f · Review Events and make corrections

Go to Events and look through today's records.
For a missed student, use Manual correction: pick the student, choose Mark present or Mark absent, choose Entry or Exit, type a reason/note (required), then Save.
For a wrong or duplicate record, click Void to cancel it. Changed your mind? Click Restore.

TipWrite useful notes ("arrived late with parent", "camera offline 8:00–8:20"). Every correction appears in the audit log.

g · Run Reports and export

Go to Reports. Filter by class, student and date range.
Read the results: present/absent, first and last seen, and dwell time.
Click Download CSV to open it in a spreadsheet, or Print / save as PDF to print or save it through your browser.

5Tuning in week 1

The pilot test went well, but real cameras are harder than a test clip. Treat the first week as the real test and adjust based on what you see.

What the pilot test showedOn a 60-second test clip built from a public research photo set (LFW), all 4 enrolled people were recognised, with no false matches and no duplicates. Real entrances have crowds, bad light and odd angles — expect to tune.

Problem: wrong student logged (false match)

Raise match_threshold on Settings a little (default 0.45; higher = stricter).
Void the wrong events on Events.
Change one thing at a time and watch for a day.

Problem: students missed

Add more and better photos (same student ID adds to existing).
Lower match_threshold slightly — small steps only.
Check min_face_px isn't ignoring faces that are too small.
Improve camera placement and lighting (section 3).

The settings you can change

All of these are on Settings → Recognition & privacy settings. Changes are recorded in the audit log.

Setting	What it means
`match_threshold`	How close a face must be to count as a match. Default 0.45; higher = stricter (fewer false matches, more missed students).
`vote_frames`	How many frames must match before logging (3 in the default "3 of the last 5").
`vote_window`	How many recent frames are considered (5 in the default "3 of the last 5").
`cooldown_seconds`	How long before the same student can be logged again on the same camera (5 minutes by default).
`process_fps`	Frames analysed per second per camera (about 5). Lower uses less CPU.
`min_face_px`	Faces smaller than this (in pixels) are ignored.
`retention_days`	Events older than this are deleted automatically. Default 365.
`keep_thumbnail`	1 = keep one small thumbnail per student; 0 = keep none.

Still not accurate enough?The system can switch to a more accurate face model, buffalo_l, with one server setting. The catch: everyone must be re-enrolled afterwards, and it needs more computing power. Decide early — ideally before enrolling the whole school. See the appendix.

6Daily & weekly routine for staff

A few minutes a day keeps the records accurate. The system is an assistant, not the final word — a teacher's correction always wins.

Every morning

Open Live; check every camera shows an fps figure.
Watch the present today count rise during arrival.
Note students you know arrived but aren't shown.

After arrival / end of day

Review Events; fix missed students with Mark present / Mark absent plus a note.
Void wrong or duplicate records.
Run today's report on Reports if your school needs a daily register.

Every week

Download CSV or Print / save as PDF the weekly report.
Principal reviews the Audit page: logins, corrections, exports, settings changes.
Enroll new students (with consent); add photos for students who are often missed.
Remove students who have left on Students.
Delete accounts for staff who have left on Users.
Check for students who are often missed or often wrongly logged; adjust per section 5.

7Privacy & data handling summary

What is kept

Name, student ID and class.
A face fingerprint (embedding): 512 numbers, not a photo.
Optionally one small thumbnail per student (keep_thumbnail = 1; set 0 for none).
Attendance events (entry/exit times, corrections and notes) — deleted automatically after retention_days (default 365).
An audit log of logins, enrollments, corrections, exports and settings changes.

What is not kept

No video recordings.
No camera frames.
Enrollment photos are discarded after processing.
Camera passwords are hidden on the dashboard.

Your responsibilities

Collect and record consent before enrolling; put notice signs near cameras.
Give access only to people who need it, with the lowest role that works. Remember teachers can currently see all classes.
Treat CSV and PDF exports as personal data: store them securely and delete them when no longer needed — the automatic retention only covers data inside the system.
Follow your local data-protection law and the retention period you agreed.
Remove students who leave, or whose parents withdraw consent.

8Troubleshooting

Most problems come down to the camera connection, lighting, or enrollment photos.

Problem	Likely cause	What to do
Camera offline / no fps on Live	Camera off or unplugged; network can't reach it; wrong URL, username or password; camera switched off in the dashboard.	Check the camera has power and the server can reach its IP. Re-check the RTSP URL format and credentials from the installer. Check the camera is switched on on Cameras. Short drop-outs reconnect automatically.
Camera works but no faces detected	Camera too high or far away; backlight; dim light; faces smaller than `min_face_px`.	Watch faces seen on Live. Move the camera to face/eye level, closer to where students walk, with light on their faces. Check `min_face_px`.
A student is never recognised	Not enrolled, or poor/too few photos; photos from a very different angle; threshold too strict.	Check they're on Students. Add 5–10 better photos with the same student ID, ideally at the camera's angle. If many students are missed, lower `match_threshold` slightly. Mark them present by hand meanwhile.
Wrong student logged	Threshold too loose; similar-looking students; poor photos.	Void the event. Raise `match_threshold` slightly. Improve the photos for both students. Consider `buffalo_l` (section 5).
Duplicate logs	Student seen by more than one camera (each camera logs separately); `cooldown_seconds` too short; same person enrolled twice under different student IDs.	Void duplicates on Events. Check `cooldown_seconds` (default 5 minutes). Make sure each student has only one student ID.
Server slow / Live lagging	Too many active cameras for the CPU (~2 cores each); main stream used instead of substream.	Use each camera's substream URL. Switch off unused cameras. Lower `process_fps`. Plan a GPU before going past about 6–8 cameras.
Photo rejected at enrollment	No face found, or more than one face.	Use a clear photo with only that student's face, well lit, no hat or sunglasses.

9Scaling up & what's coming later

Growing from pilot to whole school

Prove the pilot first: one entrance camera, one class, at least a week of good results with few corrections.
Decide on the face model before enrolling everyone. Moving to the more accurate buffalo_l is one server setting but requires re-enrolling every student.
Add cameras gradually. Each active camera uses about 2 CPU cores at ~5 frames/sec. The current server (20 cores, no GPU) is fine for about 2–4 cameras.
Plan an NVIDIA GPU before going past about 6–8 cameras, or before adding exam monitoring once it exists.
Enroll class by class, collecting consent as you go, and watch Live each time a new class starts.

Setup	Current server (20 CPU cores, no GPU)
1 camera	~5 frames/sec, ~2 CPU cores
2–4 cameras	Fine for a pilot
Beyond ~6–8 cameras	Plan an NVIDIA GPU first

Not built yet

These features are not available today. Don't plan school processes that depend on them:

Exam invigilation.
Anti-spoofing beyond multi-frame matching (a printed photo may fool the system).
Restricting teachers to their own classes.
Built-in PDF export (use Print / save as PDF through the browser).
Capturing enrollment photos straight from a camera.

10Go-live checklist

Print the PDF version of this page and tick each item at your go-live meeting.

Permissions & policy

☐ Consent collected and recorded for every enrolled student
☐ Parent/student information letter sent
☐ Notice signs posted near every camera
☐ Local data-protection requirements checked
☐ Retention period agreed and retention_days set
☐ keep_thumbnail decision made (1 or 0)

Accounts

☐ Admin password held safely by agreed person(s)
☐ Individual accounts created on Users
☐ Roles checked (teacher / principal / admin)
☐ Staff know teachers can see all classes

Cameras

☐ Entrance camera(s) at face/eye level, front-lit, no backlight
☐ Substream RTSP URLs used
☐ Correct zone set (Classroom / Entrance / Exit)
☐ Every camera shows fps on Live
☐ Number of cameras within server capacity

Data

☐ DEMO class and its 4 test people deleted
☐ Face model decided (buffalo_sc or buffalo_l) before full enrollment
☐ Pilot class enrolled with 5–10 good photos each
☐ Student IDs and class names checked for typos

Pilot results

☐ At least one week of pilot running
☐ Missed students fixed (photos / threshold / placement)
☐ False matches reviewed; match_threshold tuned
☐ Duplicate logs checked
☐ Report run and CSV / PDF export tested

Routine

☐ Staff trained on Live, Events, Reports
☐ Staff know how to make manual corrections with a note
☐ Person named for daily Events review
☐ Principal scheduled for weekly Audit review
☐ Process for new students and leavers agreed

Approved by (name & role) · Signature · Go-live date

AAppendix: technical notes

For the person installing or maintaining the server.

Stack

Everything lives in /home/jb/attendance on the server and runs as three Docker services:

Service	Role
`att-db`	PostgreSQL with pgvector — stores students, face embeddings, events, settings and the audit log.
`att-api`	FastAPI — serves the web dashboard at attendance.nostr.africa.
`att-worker`	Video processing — reads camera streams/files, detects and recognises faces, writes events.

To (re)start the stack, from /home/jb/attendance run: docker compose up -d

Recognition pipeline

InsightFace: SCRFD face detector + ArcFace 512-dimension face embedding.
Default model pack buffalo_sc, running on CPU.
Logged when similarity ≥ match_threshold (0.45) in vote_frames of the last vote_window frames (3 of 5).
Per-camera cooldown: cooldown_seconds (5 minutes). Entrance/Exit zones give entry/exit times and dwell time.
No video or frames are stored; enrollment photos are discarded after the embedding is computed.

Changing the face model

The model is set with FACE_MODEL in the .env file in /home/jb/attendance. Switching to buffalo_l (more accurate) is one setting, then restart with docker compose up -d.

WarningEmbeddings from different models are not interchangeable. After changing FACE_MODEL, every student must be re-enrolled. buffalo_l is also heavier — check capacity, and plan a GPU for larger installs.

Cameras & media

Hikvision substream: rtsp://user:pass@IP:554/Streaming/Channels/102
Dahua substream: rtsp://user:pass@IP:554/cam/realmonitor?channel=1&subtype=1
Video files: place in /home/jb/attendance/media/, enter /media/name.mp4 as the URL.
Lost RTSP connections are retried automatically.

Capacity

Current server: 20 CPU cores, no GPU. ~5 frames/sec per camera (process_fps), ~2 CPU cores per active camera. Suitable for a 2–4 camera pilot; add an NVIDIA GPU before going past ~6–8 cameras or adding exam monitoring.

Need help?

We are happy to help you get started. Contact Nostr Africa (Mugisha Jean):

WhatsApp	+250 787 176 382 · wa.me/250787176382
Email	jmugisha789@gmail.com
Website	nostr.africa · all guides: nostr.africa/documentation