BlockID Portal — Deployment Guide

1. Overview & Architecture

BlockID Portal is a server-rendered PHP application backed by a single MySQL database. There is no client-side framework, no build step, and no third-party package manager: the codebase is pure PHP using PDO with prepared statements throughout. All HTML is generated on the server; the browser receives plain markup and static assets.

The application is organized around a project root that contains the front controller and the functional areas of the app:

• index.php — the application front controller (the document root points here).
• /modules — the server-rendered feature pages (organizations, users, schemas, credentials, the ledger view, etc.).
• /api — stateless JSON endpoints such as /api/credential-status.php and /api/verify-credential.php used for credential lookups and verification.
• /assets — static CSS, JavaScript, and images.
• /config, /core, /storage — sensitive internal directories that must never be reachable over HTTP.
• /install — the one-time web installer (deleted after setup).

The "ledger" is the application's audit backbone. It is an append-only, hash-chained set of rows in MySQL: each block stores a hash of its payload plus the hash of the previous block, forming a tamper-evident chain. This makes unauthorized after-the-fact edits detectable, but it is not a distributed blockchain — there is no consensus, no peers, and no proof-of-work. It is best described as tamper-evident, not tamper-proof. Administrators validate the chain on demand using the "Verify Ledger Integrity" button on the Ledger page.

2. Server Requirements

You can confirm the loaded PHP extensions quickly:

php -v
php -m | grep -Ei 'pdo_mysql|openssl|mbstring|json|opcache'

3. PHP Configuration

Tune php.ini (or a dedicated drop-in such as /etc/php/8.2/fpm/conf.d/99-blockid.ini) for production. The goal is to hide internal errors from visitors, log them privately, and keep the runtime fast and locked down.

; --- Error handling (production) ---
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/blockid/php-error.log     ; outside the web root

; --- Hide PHP from response headers ---
expose_php = Off

; --- Sessions: secure cookies ---
session.cookie_secure = 1        ; HTTPS only
session.cookie_httponly = 1      ; no JS access
session.cookie_samesite = "Lax"  ; or "Strict" if no cross-site flows
session.use_strict_mode = 1

; --- Resources ---
memory_limit = 256M
upload_max_filesize = 8M
post_max_size = 12M
max_execution_time = 30

; --- OPcache (production) ---
opcache.enable = 1
opcache.validate_timestamps = 0   ; reload manually on deploy (see Upgrades)
opcache.memory_consumption = 128
opcache.max_accelerated_files = 10000

4. MySQL Setup

Create a dedicated database using the utf8mb4 character set and a least-privilege application user that can only touch the app schema. Run the following as an administrative MySQL account:

-- Database
CREATE DATABASE blockid
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

-- Application user (use a long, random password)
CREATE USER 'blockid'@'10.0.0.5'
  IDENTIFIED BY 'CHANGE_ME_to_a_strong_random_password';

-- Privileges (see note about install-time DDL below)
GRANT SELECT, INSERT, UPDATE, DELETE,
      CREATE, ALTER, INDEX, REFERENCES, DROP
  ON blockid.* TO 'blockid'@'10.0.0.5';

FLUSH PRIVILEGES;

Restrict the user's host ('blockid'@'10.0.0.5' in the example) to the application server's address rather than '%'. If the database lives on the same host as the app, use 'blockid'@'localhost'.

-- OPTIONAL: reduce privileges after a successful install
REVOKE CREATE, ALTER, INDEX, REFERENCES, DROP ON blockid.* FROM 'blockid'@'10.0.0.5';
FLUSH PRIVILEGES;

5. Apache Deployment

Point the DocumentRoot at the project root (the folder containing index.php), not at a public/ subdirectory. The repository ships a root .htaccess that performs URL rewriting, denies the sensitive paths, and forwards the Authorization header to PHP — so AllowOverride All must be set for that file to take effect. Enable the required modules first:

sudo a2enmod rewrite headers ssl
sudo systemctl reload apache2

A representative TLS virtual host:

<VirtualHost *:443>
    ServerName portal.example.com
    DocumentRoot /var/www/blockid          # project root (contains index.php)

    SSLEngine on
    SSLCertificateFile      /etc/letsencrypt/live/portal.example.com/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/portal.example.com/privkey.pem

    <Directory /var/www/blockid>
        AllowOverride All                  # required so the shipped .htaccess applies
        Require all granted
        Options -Indexes -MultiViews       # no directory listings
    </Directory>

    ServerSignature Off
    ErrorLog  /var/log/blockid/apache-error.log
    CustomLog /var/log/blockid/apache-access.log combined
</VirtualHost>

# Redirect plain HTTP to HTTPS
<VirtualHost *:80>
    ServerName portal.example.com
    Redirect permanent / https://portal.example.com/
</VirtualHost>

6. Nginx Deployment

Nginx does not read .htaccess, so the repository ships nginx.conf.sample with the equivalent rules. Use it as the basis for your server block. It sets the document root to the project root, routes PHP to PHP-FPM, forwards HTTP_AUTHORIZATION so credential verification works, and contains the location blocks that deny the sensitive paths.

server {
    listen 443 ssl;
    server_name portal.example.com;
    root /var/www/blockid;                 # project root (contains index.php)
    index index.php;

    ssl_certificate     /etc/letsencrypt/live/portal.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portal.example.com/privkey.pem;

    # Deny sensitive directories and file types (mirrors the shipped sample)
    location ~ ^/(config|core|storage)/ { deny all; return 403; }
    location ~* \.(sql|md|sample)$       { deny all; return 403; }
    location = /config.example.php       { deny all; return 403; }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # Forward the Authorization header to PHP (required for verification)
        fastcgi_param HTTP_AUTHORIZATION $http_authorization;
    }

    server_tokens off;                     # hide Nginx version
}

server {
    listen 80;
    server_name portal.example.com;
    return 301 https://$host$request_uri;
}

7. HTTPS / TLS

Production deployments must run over HTTPS. Obtain a certificate from your organization's CA or a provider such as Let's Encrypt (conceptually: issue a cert for portal.example.com, install the full chain and private key, and renew it automatically). Then:

1. Force HTTP → HTTPS. Redirect all port-80 traffic to port 443 (see the Apache and Nginx examples above).
2. Set COOKIE_SECURE=true in config/config.php and session.cookie_secure = 1 in PHP so session cookies are only sent over TLS.
3. Enable HSTS only once you are fully on HTTPS with a valid certificate. Premature HSTS can lock users out if anything is still served over plain HTTP.

# Apache (in the :443 vhost), or Nginx via add_header
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"

8. Installation Steps

The application self-installs through a one-time web installer. Follow these steps in order:

1. Deploy the project files to the server (e.g. /var/www/blockid) and set ownership and permissions per section 9.
2. Configure the web server with the document root at the project root and reload it (sections 5–6).
3. Create the MySQL database and least-privilege user (section 4), keeping DDL rights for the install.
4. In a browser, visit https://portal.example.com/install/index.php.
5. Fill in the installer form: database credentials, the application URL, and the details for the first super administrator.
6. The installer writes config/config.php from the config/config.example.php template (generating APP_KEY, a base64-encoded 32-byte AES key), loads install/schema.sql, and — if you opt in — install/seed.sql. It then creates the first organization, the super admin account, and the genesis ledger block.
7. Delete the /install directory (see the warning box below).
8. Optional: load additional demo data with php install/seed.php --confirm (only meaningful before you delete the installer scripts, and only on non-production demos).

rm -rf /var/www/blockid/install

9. File & Directory Permissions

Application files should be owned by the deploy user with the web server's group, so the server can read code and assets but cannot rewrite the application. Only storage/ needs to be writable by the web server.

cd /var/www/blockid
sudo chown -R deploy:www-data .
sudo find . -type d -exec chmod 750 {} \;
sudo find . -type f -exec chmod 640 {} \;
sudo chmod -R 770 storage storage/logs
sudo chmod 640 config/config.php       # readable by group, never world-readable

10. Environment Hardening

• APP_ENV=production in config/config.php — hides stack traces and verbose errors in the UI.
• expose_php Off in PHP and ServerSignature Off / server_tokens off on the web server — stop leaking software versions.
• Disable directory listing (Options -Indexes on Apache; Nginx does not list by default).
• Keep /config, /core, and /storage unreachable over HTTP — rely on the shipped .htaccess / nginx.conf.sample deny rules and verify they return 403 (see section 14).
• Least privilege for the database user — grant only on the app schema, scoped to the app host, and reduce to DML after install (section 4).
• Firewall MySQL so port 3306 is reachable only from the application host (or bind it to localhost when co-located).
• Use COOKIE_SECURE=true and confirm the session timeout, BCRYPT_COST, login-lockout, and rate-limit settings in config.php are appropriate for your threat model.
• Consider fail2ban to throttle brute-force attempts at the network edge, in addition to the app's own login lockout and rate limiting.
• Keep the OS, PHP, and MySQL patched on a regular cadence.

11. Cron Jobs (Optional but Recommended)

The application functions correctly without any cron jobs, but a few periodic maintenance tasks keep tables tidy and reporting accurate. Schedule them as the deploy user.

# /etc/cron.d/blockid  (run as the deploy user)

# Every 15 min: purge stale rate-limit and password-reset rows
*/15 * * * * deploy mysql blockid -e "DELETE FROM rate_limits WHERE expires_at < NOW();"
*/20 * * * * deploy mysql blockid -e "DELETE FROM password_resets WHERE expires_at < NOW();"

# Daily 02:30: mark expired credentials (cosmetic / reporting only)
30 2 * * *  deploy mysql blockid -e "UPDATE credentials SET status='expired' \
  WHERE expires_at < NOW() AND status='active';"

Alternatively, wrap the same logic in a maintenance PHP script and invoke it from cron:

30 2 * * * deploy php /var/www/blockid/storage/../bin/maintenance.php --sweep-credentials

12. Backup Strategy

Back up two things on independent schedules: the database and the configuration file.

Database

# Nightly logical backup (run as a user with read access)
mysqldump --single-transaction --quick --routines \
  blockid | gzip > /backups/blockid-$(date +%F).sql.gz

Use --single-transaction for a consistent snapshot without locking, retain backups off-host, and test restores regularly — an untested backup is not a backup.

Configuration

Back up config/config.php separately and securely. It contains the APP_KEY and the database credentials, so treat it as a secret: store it encrypted, with tight access control, apart from the database dumps.

13. Upgrade Strategy

1. Back up first — take a fresh mysqldump and copy the current config/config.php (section 12).
2. Enter maintenance — put the app behind a maintenance page / take it out of the load balancer so no writes happen mid-upgrade.
3. Apply the new files, preserving your existing config/config.php (do not overwrite it). Re-apply file permissions from section 9.
4. Run any new migrations — if the release ships schema changes, temporarily restore DDL grants (section 4) and apply them, then reduce privileges again.
5. Reload PHP-FPM / Apache so opcache picks up the new code (required when opcache.validate_timestamps = 0).
6. Verify ledger integrity — sign in and run "Verify Ledger Integrity" on the Ledger page to confirm the hash chain is intact after the upgrade.
7. Exit maintenance and run the post-install verification (section 14).

14. Post-Install Verification

After installing or upgrading, confirm the deployment end to end:

1. Sign in as the super administrator created during install.
2. Create a test organization, a user, and a credential schema.
3. Issue a credential against that schema to the test user.
4. Verify the credential through the UI and confirm it shows as valid.
5. Revoke the credential and confirm its status updates accordingly.
6. Open the Ledger page and run "Verify Ledger Integrity" — it should report the chain as intact.
7. Exercise the API endpoints directly, e.g. https://portal.example.com/api/credential-status.php and https://portal.example.com/api/verify-credential.php, and confirm sane JSON responses.
8. Confirm the sensitive paths are blocked — each should return HTTP 403:

   curl -I https://portal.example.com/config/config.php
   curl -I https://portal.example.com/core/
   curl -I https://portal.example.com/storage/

9. Confirm /install is gone — https://portal.example.com/install/index.php should return 404.

15. Checklists

Production checklist

• Document root points at the project root (contains index.php), not public/.
• PHP 8.2+ with pdo_mysql, openssl, mbstring, json, and opcache.
• APP_ENV=production and display_errors=Off; PHP errors logged outside the web root.
• MySQL 8 database in utf8mb4 with a least-privilege app user.
• HTTPS enforced; HTTP redirects to HTTPS; COOKIE_SECURE=true.
• File/dir permissions applied; config/config.php is 640 and not web-writable.
• /install directory deleted.
• Backups scheduled (DB + config separately) and a restore tested.
• Post-install verification (section 14) completed successfully.

Security checklist

• /config, /core, /storage return 403 over HTTP.
• *.sql, *.md, *.sample, and config.example.php are denied.
• expose_php Off and ServerSignature Off / server_tokens off.
• Directory listing disabled.
• MySQL firewalled to the app host (or bound to localhost); strong DB password.
• DB user reduced to DML after install; DDL granted only during migrations.
• HSTS enabled only after full HTTPS is confirmed.
• Login lockout and rate limits reviewed; fail2ban considered.
• APP_KEY backed up securely and separately.
• OS, PHP, and MySQL patched on a schedule.