Installation and Configuration Guide

1. Overview

This guide covers deploying the PLSS Monument Field Tool and Survey Parcel Drawing Tool to a shared hosting environment for the first time, or applying updates to an existing installation. It also documents every migration applied to the live database at surveyor.weist.net as a permanent record.

The system consists of:

• index.html — Main PLSS field tool (formerly plss-field-tool.html)
• parcel-drawing-tool.html — Survey Parcel Drawing Tool
• survey-math.js — Shared geodetic math library (GRS80 constants, LCC/TM projections, SP_ZONES). Required by both index.html and parcel-drawing-tool.html. Must be deployed alongside both files.
• profile.html — User profile page
• manuals.html and five manual/guide HTML files
• Approximately 30 PHP API files
• A MySQL database (weistne1_Surveyor)
• A /photos/ directory for report photo uploads

2. Prerequisites

• FTP client (FileZilla recommended) or cPanel File Manager access
• phpMyAdmin access via cPanel
• PHP 8.0 or higher (tool currently runs on 8.2.30)
• MySQL 5.7 or higher
• A working email account for outgoing password reset and notification emails

3. Database Setup

3.1 Create the Database

1. Log into cPanel
2. Navigate to MySQL Databases
3. Create a new database — e.g. yourprefix_Surveyor
4. Create a database user — e.g. yourprefix_SurvAD
5. Set a strong password and record it securely — you will need it for config.php

3.2 Assign Permissions

Under Add User to Database in cPanel MySQL Databases:

Installation-only — remove after setup: ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, DROP, EVENT, INDEX, TRIGGER

Permanent running-state — keep always: SELECT, INSERT, UPDATE, DELETE, EXECUTE, SHOW VIEW, LOCK TABLES, REFERENCES

3.3 Run the Schema

1. Open phpMyAdmin from cPanel — always launch it from inside cPanel, never from a bookmarked URL
2. Click your database name in the left panel to select it
3. Click the SQL tab
4. Paste and run plss_schema.sql
5. Verify no errors — you should see 20+ tables created

3.4 Seed Initial Data

After the schema runs, insert your organization and first admin user. Replace all placeholder values:

-- Organization record
INSERT INTO organizations (
    org_name, org_short, is_active, tier,
    firm_name, firm_address, firm_phone,
    firm_website, firm_email, created_at
) VALUES (
    'Your Firm Name', 'YOURCODE', 1, 'professional',
    'Your Firm Name',
    'Your Address, City, State ZIP',
    'Your Phone Number',
    'yourwebsite.com',
    'info@yourfirm.com',
    NOW()
);

-- First admin user
-- Password hash below = 'ChangeMe1'
-- User is forced to change on first login
INSERT INTO users (
    org_id, username, email, personal_email,
    display_name, password_hash,
    license_type, license_number, license_state,
    must_reset_password, is_active,
    is_email_verified, failed_login_count, created_at
) VALUES (
    1, 'admin', 'admin@yourfirm.com', 'admin@yourfirm.com',
    'Your Name',
    '$2y$12$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.usu5NW54i',
    'PLS', 'your_license_number', 'CA',
    1, 1, 1, 0, NOW()
);

-- Assign System Architect role
INSERT INTO user_roles (
    user_id, role_id, granted_by,
    granted_at, granted_reason, is_active
) VALUES (1, 1, 1, NOW(), 'Initial setup', 1);

3.5 Remove Installation Permissions

After the schema and seed data run successfully, return to cPanel MySQL Databases and remove: ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, DROP, EVENT, INDEX, TRIGGER.

4. File Upload

4.1 Directory Structure

All files go into the document root for your domain. Use FTP (FileZilla) for files over 300KB — never the cPanel File Manager for large files.

index.html                    ← main tool (formerly plss-field-tool.html)
parcel-drawing-tool.html
profile.html
manuals.html
user-guide.html
admin-guide.html
install-config-guide.html
howto-guide.html
sql-reference-guide.html      ← new v2.2
config.php
auth.php
login.php
logout.php
save-search.php
get-searches.php
save-monument.php
get-monuments.php
save-correction.php
get-correction.php
create-user.php
update-user.php
list-users.php
get-audit.php
org-settings.php
forgot-password.php
reset-password.php
parcel-lookup.php
cors-proxy.php                ← includes DCA verify endpoint
api-proxy.php
get-profile.php
update-profile.php
update-org.php
search-monuments.php
save-report.php               ← new v2.2 — Reports system
get-reports.php               ← new v2.2
get-report.php                ← new v2.2
finalize-report.php           ← new v2.2
recall-report.php             ← new v2.2
upload-report-photo.php       ← new v2.2
cron-reports.php              ← new v2.2 — runs via cPanel cron
photos/                       ← new v2.2 — report photo storage (see 4.3)

4.2 File Permissions

4.3 Photos Directory

The Reports system stores uploaded field photos in a /photos/ directory on the server. This directory must exist and must NOT be directly web-accessible.

1. Create the directory: public_html/photos/
2. Set permissions to 750
3. Create a .htaccess file inside /photos/ containing:

Deny from all

This prevents anyone from accessing photo files directly via URL. Photos are served through PHP endpoints that enforce authentication — not directly from the web server.

Photos are organized as: /photos/{org_id}/{report_id}/photo_N.jpg

5. Configuration

5.1 Edit config.php

Edit config.php before uploading — fill in all values marked with your actual credentials:

// ── DATABASE ──────────────────────────────────────────
define('DB_HOST',    'localhost');
define('DB_NAME',    'yourprefix_Surveyor');
define('DB_USER',    'yourprefix_SurvAD');
define('DB_PASS',    'YOUR_ACTUAL_DB_PASSWORD');   ← must be set
define('DB_CHARSET', 'utf8mb4');

// ── APPLICATION ───────────────────────────────────────
define('APP_NAME',    'PLSS Monument Field Tool');
define('APP_VERSION', '2.2.0');
define('APP_URL',     'https://surveyor.weist.net'); ← your domain

// ── SMTP ──────────────────────────────────────────────
define('SMTP_PASSWORD', 'YOUR_ACTUAL_SMTP_PASSWORD'); ← must be set

// ── DCA LICENSE VERIFICATION ──────────────────────────
define('DCA_API_KEY', '');  ← leave empty until key obtained

// ── PRODUCTION SETTINGS ───────────────────────────────
define('DEBUG_MODE', false);  ← always false in production
define('PDO::ATTR_PERSISTENT', false); ← keep false on shared hosting

5.2 DCA API Key (License Verification)

The DCA API key enables real-time California professional license verification for report finalization. Without it, finalization is blocked.

1. Register at iservices.dca.ca.gov
2. Email iservices@dca.ca.gov — request access to BPELSG (Board for Professional Engineers, Land Surveyors, and Geologists) license data specifically
3. Once you receive a key, set define('DCA_API_KEY', 'your-key-here'); in config.php
4. Upload config.php (with passwords re-entered)

Until the key is configured, the system returns API_NOT_CONFIGURED and displays a message directing users to contact the administrator.

5.3 The config.php Password Rule

6. SMTP Email

SMTP settings are configured through the Admin Console after login. The tool uses direct SMTP — not PHP's mail() function — for reliability on shared hosting.

The SMTP password is set in config.php — not in the database. After saving SMTP settings in the Admin Console, use Send Test Email to confirm delivery, then Full SMTP Diagnostic if it fails.

7. Cron Job Setup

A nightly cron job is required to flip Draft reports to public visibility after 180 days and to flag DPR reports when newer field data is logged for the same section.

Setting Up in cPanel

1. Log into cPanel
2. Navigate to Cron Jobs
3. Add a new cron job with the following settings:

This runs cron-reports.php at 2:00 AM daily. Output is appended to a log file. Adjust the path to match your actual home directory.

What the Cron Job Does

• Finds Draft reports where DATEDIFF(NOW(), created_at) >= 180 and report_status = 'DRAFT' — sets visible_public = 1
• Finds DPR reports for sections that now have a section correction logged — sets a flag in report_body JSON
• Recalled reports are never made public — the WHERE clause requires DRAFT status

8. First-Time Setup

After database setup, file upload, and config.php configuration:

1. Navigate to surveyor.weist.net — you should see the login screen
2. Log in with username admin and password ChangeMe1
3. You will be forced to set a new password immediately
4. After login, click Admin tab
5. Enter firm information in the right-hand panel — firm name, address, phone, email, website
6. Enter SMTP settings and send a test email to confirm delivery
7. Create user accounts for your team (see Admin Guide Section 3.1)
8. Create the photos directory and set up the cron job (Sections 4.3 and 7)

9. Migrations

9.1 Process

1. Log into cPanel → MySQL Databases
2. Temporarily grant ALTER, CREATE, DROP, INDEX to weistne1_SurvAD
3. Open phpMyAdmin → click weistne1_Surveyor in left panel → SQL tab
4. Paste and run the migration file
5. Verify no errors
6. Return to cPanel → Set Privileges → remove schema-change permissions
7. Test login to confirm the web application still connects correctly

9.2 MySQL Compatibility Notes

• Do not use IF NOT EXISTS in ALTER TABLE statements — not supported on shared hosting MySQL
• If an ALTER fails because the column already exists, skip that statement and continue
• All foreign key column types must match exactly — use INT(10) UNSIGNED throughout to match the existing schema
• If #1215 — Cannot add foreign key constraint appears, check that referenced table primary key names and types match exactly using SHOW CREATE TABLE tablename;
• Use INSERT IGNORE for permission and role seeding so re-running is safe

9.3 Migration History — surveyor.weist.net

Complete record of all migrations applied to the live database, in order:

10. How Data Flows

Field Workflow

1. User runs Q/QQ Lookup → gets computed corner coordinates, elevation, declination
2. User logs field search attempt in Monument Log → saved to search_log table
3. If monument found: user creates MFR in Reports tab, linking to the log entry via search_log_id
4. Licensed Surveyor reviews draft MFR, verifies corner designation and description, finalizes under license number
5. If warranted: user generates Corner Record from Monument Log entry → saved to monuments table, printed and filed with county

Drawing Workflow

1. User runs Q/QQ Lookup or enters COGO traverse
2. Clicks Open in Drafting Tool
3. Tool fetches user profile and firm data from get-profile.php
4. Packages all geodetic data + firm info into localStorage handoff payload
5. Drafting Tool opens, reads payload, pre-populates everything including firm title block

Report Filename Convention

MtDiablo-04N-06E-Sec14-NWSW-MFR-2026-04-16-WEI-RW-Draft
{Meridian}-{TWP}-{RNG}-{Section}-{Corner}-{Type}-{Date}-{OrgCode}-{Initials}-{Status}

Meridian names: MtDiablo, Humboldt, SanBern, SaltLake, NewMexico, 6thPrincipal, GilaSalt, Navajo, Willamette. Corner codes: NWSW, SENE, LT04 (lot corners), CNTR, NQ00, SQ00, EQ00, WQ00, XXXX (not applicable). Status: Draft, Final (Recalled not in filename). OrgCode comes from organizations.org_short.

11. Security Checklist

• config.php has correct database credentials (DB_PASS is not a placeholder)
• config.php has SMTP_PASSWORD set to actual email password
• DEBUG_MODE is set to false in config.php
• PDO persistent connections are false in config.php
• All .php files are permission 640
• All .html files are permission 644
• photos/ directory exists, is permission 750, and has Deny from all in .htaccess
• Schema-change database permissions removed after initial setup and after each migration
• First admin password changed from default ChangeMe1
• APP_URL in config.php matches actual domain exactly
• Firm information entered via Admin Console
• SMTP test email received successfully
• Cron job set up and confirmed running in cPanel Cron Jobs
• DCA_API_KEY set in config.php (or documented as pending)
• All new PHP files use get_db() — not new PDO() with $db_host variables
• All new PHP files use Auth::require_auth() — not Auth::require_login() which does not exist
• All JavaScript fetch calls include Authorization: Bearer token header

12. File Reference

13. Troubleshooting