Set up your private workspace

# FieldKit setup

FieldKit is free to download. Each business supplies its own PHP/MySQL hosting,
domain and SMTP mailbox. No PFlix account or shared customer database is used.
The included forms are geared toward pest-control field work.

## 1. Prepare your hosting

Use a domain or subdomain with HTTPS and an empty web root. Keep this separate
from another application's existing app-api, r or office folders. Requirements:
PHP 8.2 or newer; MySQL/MariaDB; PDO MySQL, cURL, mbstring, fileinfo and OpenSSL;
Apache/LiteSpeed with URL rewriting and support for the included .htaccess files.
Allow uploads large enough for your PDFs/photos. The app requires Android 7+.

Create a new database and database user in your hosting control panel. Keep its
password private. Do not use another business's existing FieldKit database.

## 2. Upload the server

Extract fieldkit-server.zip on your computer. Upload the **contents** of its
public_html folder into your site's public_html. Include hidden .htaccess files.
The three web folders should be app-api, r and office.

Place the contents of private-files **one level above public_html**. Rename:

- fieldkit-app-config.example.php to fieldkit-app-config.php
- fieldkit-mail-config.example.php to fieldkit-mail-config.php

Edit these two files in your hosting control panel. In the app config, enter
your database DSN/name, database username/password, your https://domain base_url,
business name/email and timezone (for example America/Winnipeg). Set install_key
to a unique random string of at least 32 characters. Never reuse the example.

In the mail config, enter your mailbox provider's SMTP host, username/password,
port/encryption and your office email. Outgoing copies go to recipient. The
business email in app Settings is Reply-To; the authenticated SMTP mailbox is
the sender. Configure your domain's SPF/DKIM through your mailbox provider.

Keep config files and fieldkit-private outside public_html. On Linux, use file
permissions 600 for private config/files and 700 for private directories. Web
files normally use 644 and web directories 755. PHP must be able to write the
private folder. No passwords or private files belong in the download page.

## 3. Create your first login

Open https://YOUR-DOMAIN/app-api/install.php. Enter your install key, name,
chosen username and a strong password. This creates the tables and first user.
Do not use the installer on someone else's domain. Remove install.php after
setup; retain your private install key for future maintenance.

## 4. Install and brand the app

Download fieldkit.apk from pflix.shop/fieldkit/ onto your Android phone. Open it
and approve installation for the browser when Android requests it. At sign-in,
enter https://YOUR-DOMAIN/app-api/ and the login you just created.

Open More > Business info. Add your logo, in-app name, business name, website,
contact details, tax registration/rates and payment email. Taxes start at zero.
Save and sync. Use a PNG or JPG logo; the app stores a PNG for reliable PDF/email
display. Every signed-in phone on your business server receives these settings.

For a name/logo on your home screen, use Add branded home-screen shortcut, then
confirm Add in Android. The installed app remains FieldKit; the shortcut uses
your business branding on supported Android 8+ launchers.

More > My profile stores each technician's name, licence and reusable signature.
More > People adds staff logins. Add your own products, documents and prices;
there are no preloaded customers, staff, products or SDS sheets. Upload the
SDS/labels matching your products. Review the included wording before using it.

## 5. Test your setup

Create a test customer, appointment, report, quote and invoice. Check the draft
preview for your details and logo. Send a test email to yourself, open its
customer link and return a signature. Sync and verify the signed copy in Inbox.
Confirm that both your mailbox and customer mailbox receive the completed copy.

Reports record work; invoices record payments. Signing a quote does not create
a recurring service plan. Set the customer's plan and book its due visits.
Enable job reminders in More > Reminder settings and allow notifications in
Android. Reminders use each phone's local time. Keep its time zone correct.

## Updates and backups

The matching version.json is supplied inside private-files/
fieldkit-private/app-apk. Copy your downloaded fieldkit.apk into that folder,
then put this directory beside your private config files.
When a new release is available, replace those two files with the official pair;
then signed-in phones can offer that version. Keep the app's signing identity
unchanged. Update PHP web files while preserving your private config/database.

Back up the MySQL database, private config and the entire fieldkit-private
directory regularly using your hosting provider. Keep a second copy off-site.
The optional archive-tools folder stays outside public_html and needs a local
PHP runtime with cURL/PDO SQLite. Run:

    php archive-tools/pull_archive.php --login --dir=/YOUR/PRIVATE/ARCHIVE
    php archive-tools/pull_archive.php --dir=/YOUR/PRIVATE/ARCHIVE

The tool prompts for your own server and login. Schedule the second command
with your OS task scheduler if desired. Its saved login token is private.

Returned-signature email retries run with normal API/customer-link traffic. For
reliable retries even without traffic, schedule the included private CLI tool:

    php /PATH/maintenance/retry_signed_copies.php /PATH/public_html/app-api

Set CPPC_APP_CONFIG to your absolute private FieldKit config path when running
CLI tools. That environment variable is an internal compatibility identifier.

To use a different business server on a phone, sync and back up its current work
first, then clear FieldKit's app storage in Android Settings before signing in.
This keeps one business's offline records from being uploaded to another.

Support: Perry_mason2@hotmail.ca