LongField Manual Installation Guide

Document status: Manual administrator guide for the current source reference. A verified customer release package, dependency lockfile, production configuration matrix, and release-specific install/upgrade commands are not published yet. Verify every package-specific step against the release-specific installation notes included with the packaged release.

This path is designed for administrators using their own shell, editor, and technical team. AI tools are optional. Do not use development defaults or sample credentials for a production installation.

Verified platform facts

• The available LongField source is a Python / Flask application using SQLAlchemy and Flask-Migrate.
• run.py explicitly refuses to start the Flask development server and directs operators to the configured Gunicorn / systemd service.
• The source documents SQLite for development and PostgreSQL as a production-capable database option. Confirm the exact supported database and driver in the purchased release.
• The source deployment reference uses a Python virtual environment, Gunicorn, systemd, and Nginx. Its example script is a reference, not a safe drop-in customer installer; review its effects before using any deployment automation.
• Exact supported distribution, Python version, package versions, storage paths, and production topology must be taken from the verified release package.

1. Prepare the host

Choose a supported Linux host from the release-specific requirements. Record the operating system version, runtime versions, database engine/version, reverse-proxy topology, storage capacity, backup destination, administrator, and recovery owner. Keep a separate staging host or isolated environment for the first installation.

Do not open firewall ports or replace an existing proxy configuration from this general guide. Confirm the exact application listener, host names, TLS termination, upload limits, and forwarded-header policy in the packaged release notes.

2. Review and verify the package

Obtain the licensed release and matching SHA-256 value through the authorized delivery channel. Confirm the checksum using the filename and checksum format supplied with that exact package. Read the release notes, system requirements, architecture, license, and administrator guide before unpacking or running setup commands.

Do not install from a moving development branch when a versioned release is required. Preserve the original archive and its checksum in the organization’s controlled software records.

3. Create the application environment

Create a dedicated service account, application directory, configuration directory, and data/document storage locations according to the release-specific layout. Keep executable application files separate from customer data and writable document storage. Grant only the service account and designated administrators access to sensitive paths; do not make document or environment directories world-readable.

The source repository contains a Python virtual-environment pattern. Use the exact interpreter and dependency manifest supplied with the package:

python3 --version
python3 -m venv .venv

Activate the environment using the shell’s documented activation command, then install from the packaged, version-pinned dependency manifest. If the verified release does not include that manifest, stop and request the release-specific instructions rather than guessing dependency versions.

4. Configure database and storage

Select only a database engine listed for the purchased release. The available source reference uses SQLite in development and identifies PostgreSQL as a production-capable option; the customer release may narrow or change that matrix. Configure the database URL and instance/storage paths using the exact variable names in the release’s environment template. Keep secrets outside source control and limit their filesystem permissions to the service account and administrators who need them.

Create document storage on the approved persistent volume. Confirm ownership, group access, backup inclusion, capacity monitoring, and restore procedures. Do not place customer files in a public web root.

5. Initialize schema and administrator access

Read every included migration and release note before applying schema changes. Back up the empty or existing database first. Use only the packaged migration command for the exact release; do not assume that creating ORM tables is equivalent to applying reviewed migrations. Create the first administrator through the release’s documented protected setup flow. There is no default production login or password in this guide.

6. Configure service startup and reverse proxy

Use the package’s verified service unit and application entry point. The source runner rejects the Flask development server; production startup must use the configured Gunicorn/systemd path specified for the release. Configure the reverse proxy to send traffic only to the intended application listener, preserve the validated host and scheme, apply the release’s upload limits, and keep database ports private. Obtain TLS for the exact public hostnames and redirect cleartext traffic only after the HTTPS route has been verified.

Do not copy an old sample proxy or service file over an existing server configuration without reviewing each directive and preserving unrelated sites.

7. First start and validation

Start the service using the release-specific administrator instructions. Check the service state and logs, then use the documented health endpoint if provided. Validate sign-in, role and firm/workspace isolation, matter access, document upload/download permissions, calendar context, billing access, and audit behavior using fictional test records. Confirm no sample credentials, debug mode, development listener, or public data directory remains enabled.

8. Backups, upgrades, and recovery

Back up the database, environment/configuration, and document storage together using a method appropriate to the database and filesystem. Encrypt backups, restrict access, retain independent copies, and test a restore into an isolated environment before relying on the installation. Before an upgrade, record current versions and hashes, capture a restorable backup, review migration directions, rehearse the upgrade on staging, and document rollback limits. Never run a downgrade against customer data unless the release’s recovery procedure explicitly supports it.

Troubleshooting checkpoints

1. Confirm the service account can read the application and configuration and write only to intended data paths.
2. Confirm the configured runtime and dependencies match the release manifest.
3. Confirm database connectivity and that the expected migrations completed.
4. Confirm the service listens only on its configured private interface and the proxy reaches that listener.
5. Confirm TLS, hostname, proxy headers, file-size limits, and storage permissions.
6. Preserve logs and hashes before changing a failed installation. Do not expose secrets or customer records in support requests.

If an exact command, dependency, migration, or path is not stated in the verified package, verify this step against the release-specific installation notes included with the packaged release.

Working on the code manually

You can use the included guides with your own editor, IDE, development team, contractor, or command-line workflow. AI-assisted development is an option, not a requirement. Read the architecture and license first; create a version-control checkpoint or protected backup; inspect the affected routes, models, permissions, and migrations; make a scoped change; run the documented checks; review security boundaries; deploy to staging; and promote deliberately after validation. See the Developer Guide and AI Development Guide.