======================================================================== PCEA MAKUPA PARISH — CHURCH MANAGEMENT SYSTEM Running it on this computer ======================================================================== WHAT TO DO — three steps ------------------------------------------------------------------------ 1. Put this whole folder somewhere you can write to. Good: C:\pcea Bad: inside "Program Files", or left inside the ZIP file. If you are reading this from inside a ZIP window, stop: right-click the ZIP, choose "Extract All", and pick C:\ as the destination. 2. Make sure XAMPP is installed, and MySQL is running. Download: https://www.apachefriends.org Install to the default folder. Open the XAMPP Control Panel and press Start next to MySQL. (Apache is not needed.) 3. Double-click: START PCEA CHMS.bat A black window opens and tells you what it is doing. Your browser opens by itself when it is ready. The FIRST time, the setup page appears: the database details are already filled in, so you only choose the parish name, the districts, the financial year, and your own administrator email and password. Write that password down. Every time after that, the sign-in page appears. KEEP THE BLACK WINDOW OPEN while you are working. Closing it stops the system, the same way switching off a photocopier stops copying. THE OTHER TWO FILES ------------------------------------------------------------------------ STOP PCEA CHMS.bat Only needed if the black window was closed badly and the system will not start again. It frees the port and leaves MySQL alone. RESET DATABASE.bat Wipes everything on THIS computer back to a brand-new install and asks you to type RESET first. Use it after practising, or if a first install went wrong. Do NOT use it to clear practice data if you have real work entered. Instead, open the system, go to Settings, and press "Remove the practice data" — that removes only the practice rows and leaves every real entry alone. TRYING IT BEFORE ENTERING ANYTHING REAL ------------------------------------------------------------------------ On the welcome screen, press "Load practice data". It fills the system with an invented parish — six districts, about a hundred members, a year of Sundays — so you can open every report and see how it works. A yellow band appears at the top of every page while practice data is loaded, so nobody mistakes those figures for the parish's own. When you are ready, Settings → "Remove the practice data" takes it all out, and you are back at the welcome screen with a clean book. SIGNING IN ------------------------------------------------------------------------ There is NO default username or password. The first account is the one you create on the ADMINISTRATOR step during setup, and only you know it. That is deliberate: systems shipped with admin/admin stay that way for years, and this one holds the parish's giving records. The EMAIL ADDRESS box wants the email you typed at setup — not a username like "admin". Forgotten it? From this folder, at a command prompt: php tools\\accounts.php lists the accounts that exist. To set a new password for one: php tools\\accounts.php someone@parish.or.ke (Open a command prompt here by holding Shift, right-clicking this folder's empty space, and choosing "Open PowerShell window here".) Once you are in, add a SECOND administrator under Users. Vouchers must be approved by somebody other than the person who raised them, so a parish with one account cannot finish that job — and if that one account is locked out, nobody can let it back in. RUNNING BOTH SYSTEMS FOR FOUR WEEKS ------------------------------------------------------------------------ Do not stop the old workbook the day this system starts. Keep both for four Sundays, enter each Sunday into both from the counting sheets, and compare them with: php tools\parallel.php "C:\path\to\District Report.xlsx" It prints either "agrees to the shilling" or the exact differences by district. After four agreeing Sundays the workbook can be retired -- and that decision belongs in a session minute, not to the software. The full protocol is in deploy\PARALLEL-RUN.md. IF SOMETHING GOES WRONG ------------------------------------------------------------------------ The black window explains most problems in plain words. The common ones: "PHP was not found" XAMPP is not installed, or was installed somewhere unusual. Install it to C:\xampp and try again. "Could not connect to MySQL" MySQL is not running. Open the XAMPP Control Panel and press Start next to MySQL. If you gave your MySQL root account a password, open START PCEA CHMS.bat with Notepad and type it after DBADMINPASS= "PHP 8.1 or newer ... MISSING" The PHP on this computer is too old. Install a current XAMPP. "extension ... MISSING" The window names the exact line to uncomment in php.ini. "port 8080 is reserved by Windows" Not a problem — it says which port it used instead, and opens that. Anything else: take a photo of the black window and send it on. The message in it is the answer. WHAT IS INSIDE THIS FOLDER ------------------------------------------------------------------------ public\ the only folder the browser is allowed to see src\ the program itself sql\ the database schema and its updates tools\ maintenance commands (see below) deploy\ notes for putting this on a real web host _local\ helpers the launcher uses — leave these alone storage\ backups and logs this computer writes Your settings live in a file called .env, created on first run. It holds the local database password, so do not email the folder to anyone after you have started using it. FOR SOMEONE COMFORTABLE WITH A COMMAND LINE ------------------------------------------------------------------------ From this folder. If a tool says the database client was not found, run this once in the same window first — XAMPP installs it but does not put it on the PATH: set PATH=C:\xampp\mysql\bin;%PATH% From this folder: php tools\test.php run the checks — all green means this copy is sound php tools\migrate.php --status which database updates are applied php tools\preflight.php check a server before deploying The system is plain PHP and MySQL: no Composer, no Node, no framework. Copying this folder to a cPanel host and pointing the domain at public\ is a complete deployment — see deploy\DEPLOY.md. ========================================================================