Administration
Setting the system up for a real assembly, and keeping it honest afterwards.
Before anyone else signs in
- The assembly profile — name, category, region, capital, postal address and the names of the Chief Executive, Coordinating Director and Finance Officer. These print on demand notices, receipts, vouchers and permits.
- Fiscal years — create the current year and mark it active.
- Departments — with their cost centres, marking which ones generate revenue.
- Zones and electoral areas — the geography everything else hangs off. Add coordinates so the map has somewhere to place records.
- Funding sources — IGF, the Common Fund, DPAT, government transfers and any development partner.
- The chart of accounts, then the composite budget for the year.
- The fee fixing resolution as revenue items.
Roles and users
A role is a named bundle of module permissions. Create the roles your assembly actually has before you create users, then give each user exactly one. Changing a role changes what every user holding it can reach, immediately.
Do not give everyone administration. The administrator flag bypasses every module check. Two or three people at most.
Facilities
The facility register holds the assembly's own premises and the public places it answers for — offices, zonal councils, markets, lorry parks, clinics, public toilets, disposal sites. Anything marked public appears on the map residents see, with its opening hours and what it can do for them. Keep this current: it is the page residents use most.
When the map shows "Access blocked" everywhere
The background map comes from OpenStreetMap, which refuses to serve tiles to a page that
does not identify itself. The system is configured to identify itself correctly; if someone
has changed the SECURE_REFERRER_POLICY setting to
same-origin or no-referrer, the tiles will be refused and the map
fills with warning images. Put it back to
strict-origin-when-cross-origin.
If the assembly grows to the point where OpenStreetMap's volunteer servers are no longer
appropriate, set MAP_TILE_URL in the .env file to another
provider. Nothing else has to change.
When the map is empty
Every layer showing zero means nothing has a position yet. A record without its own GPS reading is drawn at the centre of its electoral area, so if the areas themselves have no coordinates, nothing has anywhere to go. Add a latitude and longitude to each electoral area, and to each facility, under Administration. The map itself will tell you which of these is the problem.
The audit trail
Every create, change and delete is logged with the user, the time and the address it came from. The trail cannot be edited from within the system. When something looks wrong in the cash book, this is where you start.
When the site will not start at all
Run python tools/preflight.py on the server. It works even when the site
itself does not, because it does not need Django to load — which is the point, since Django
failing to load is the usual complaint.
It reports which Python is running, whether that is the application's virtualenv, which
packages are installed, whether the .env file was found and read, and whether
the database answers. Nearly every deployment problem shows up in that list.
“No module named dotenv”, and most of its relatives, mean one thing:
the requirements went into the wrong Python. cPanel gives you a
source …/bin/activate command on the Setup Python App page — run that first,
then pip install -r requirements.txt.
When collecting static files fails
If collectstatic stops with MissingFileError about a
.css.map file, a stylesheet is pointing at something that was not uploaded.
Source maps only help a developer read original line numbers in a browser; nothing on the
page looks different without one, so the system reports the broken reference and finishes
the job rather than abandoning it.
Look at the path in the message. If it names a folder that has nothing to do with this
system, that folder is left over from another application sharing the same directory.
python tools/preflight.py lists what is inside static/ and points
out anything that does not belong. Delete it and collect again.
When the database refuses to migrate
If migrate stops with InconsistentMigrationHistory, saying
one migration is applied before its dependency, the database was not empty when the system
was pointed at it. It is nearly always a database reused from an earlier project or an
abandoned first attempt.
Run python manage.py migration_doctor. It reports what is actually in the
database — whether the assembly's own tables exist, how many staff accounts and receipts
are in there — and then says which of two things to do: start from a fresh empty database,
or, if the tables are present and only the bookkeeping rows are missing, run
migration_doctor --repair.
Read the count of receipts it prints before you do anything. If it says zero, there is nothing in that database worth keeping and starting again is the quick, safe answer. If it is not zero, take a backup first.
Backups
The database holds the assembly's cash book. Take a backup on a schedule, keep a copy off the server, and test a restore at least once before you need one. A backup nobody has ever restored is a hope, not a backup.
Demonstration data
A fully populated demonstration assembly can be loaded for training with
python manage.py seed_demo --reset. It clears existing records first, so it
must never be run against a live assembly.