Installation and deployment

Before you can build or publish a project, you need a running NaturaList installation on a web server. This page covers what you are deploying, what the server needs, and how to get the app live - on both static hosting platforms and PHP-capable servers.

What you are deploying

​NaturaList is a Progressive Web App: a set of static files (HTML, CSS, JavaScript) that run entirely in the browser. There is no application server, database engine, or back-end framework to maintain.

At runtime, the app reads a single compiled data file - usercontent/data/checklist.json - that you generate from your spreadsheet. The only optional server-side component is a small PHP script (update.php) that lets editors push new checklist.json files directly from the app's Manage screen without manual file transfers. Everything else is static.

Obtaining and preparing the app

Go to github.com/dominik-ramik/naturalist and download the latest release as a ZIP file. Unzip it locally - you will find a self-contained folder of static assets ready to be placed on a web server.

Before uploading anything, take a moment to personalise the files inside usercontent/identity/:

manifest.json - open it in any text editor and update these fields:

• name - full app name shown when a user installs the PWA on their device, e.g. Checklist of fauna of Neverwhere
• short_name - short name shown on a device home screen, e.g. Neverwhere fauna
• description - a brief description of your project
• background_color and theme_color - hex color values matching your project's palette

Do not modify other fields in this file, as they are required for correct PWA behaviour.

favicon.png - optionally replace it with your own square PNG icon. Leave it as-is if you have no preference for now. Once your project is well set up and populated with data, you can also replace screenshot-desktop.png and screenshot-mobile.png with screenshots of your own checklist - these appear in the PWA install prompt on supported browsers. If you do, update the sizes fields in manifest.json to match the exact pixel dimensions of your new images. This is entirely optional; the defaults work fine in the meantime.

credentials.php (PHP hosting only, optional) - if you plan to deploy on a PHP-capable server and want editors to be able to publish compiled data directly from the app's Manage screen, set up server-side publishing now: duplicate template_credentials.php in the same folder, rename the copy to credentials.php, and add your credentials to the $credentials array:

$credentials = [
    ["username" => "tim-the-taxonomist", "password" => "some!really!strong!password"],
    ["username" => "editor",             "password" => "anotherStrongP@ssw0rd!"],
];

You can add as many username/password pairs as needed - one per collaborator, for example. If you are deploying to static hosting, skip this file entirely.

Security notes

The PHP endpoint enforces HTTPS, rate-limits failed login attempts (5 failures locks the endpoint for 10 minutes), and uses constant-time comparison to protect against timing attacks. To disable server upload at any time, delete credentials.php or set $credentials to an empty array []. Never touch the update.php in the app's root folder.

These are the only files you need to edit before deployment. Everything else - data, appearance, filters, languages - is configured through the spreadsheet.

Server requirements

Requirement	Detail
Web server	Any host that can serve static files - Apache, Nginx, Netlify, GitHub Pages, etc. You can even experiment using a local web server on your computer, before going live
HTTPS	Required for PWA installation and offline capability, without it, the app will work just like any other website
PHP (optional)	Only needed for server-side data publishing from the Manage screen, you can still publish manually if you don't have a PHP-enabled server
No database	The app reads from usercontent/data/checklist.json - nothing else is required

Deployment

Choose one of the two following paths that matches your hosting setup.

---

Option A - Static hosting

Static hosting platforms (Netlify, Cloudflare Pages, GitHub Pages, static.app, and many others) serve files directly with no server-side processing. This works well for NaturaList and is often the simplest starting point - particularly for smaller or shorter-lived projects such as a course assignment, a student biodiversity survey, or a quick public checklist where the overhead of managing a PHP server is not justified. The only trade-off compared to PHP hosting is that publishing a new checklist.json and adding media files always requires a manual step - by design static hosting only serves static files.

Understanding how updates work on static hosting

This is the most important thing to check before you commit to a platform, because static hosts differ significantly in how they handle file updates after the initial deployment.

Some platforms - Netlify being a common example - treat every deployment as a complete replacement of the site. There is no in-browser file manager; if you want to update a single image or replace checklist.json, you must redeploy the entire folder. This means keeping a complete local copy of the NaturaList folder at all times and redeploying it in full for every change. The workflow is manageable, but requires discipline.

Other platforms provide an in-browser file manager that lets you navigate the site's folder structure and upload, replace, or delete individual files after deployment. For a project where media files and checklist.json are updated regularly, this is considerably more practical.

Before choosing a platform, check whether it offers granular file management - it will affect your day-to-day publishing workflow more than any other factor. static.app is one example that does; others exist. Platforms like Netlify or Cloudflare Pages are better suited to teams comfortable with Git-based workflows, where every change is committed to a repository and deployed automatically.

Choose your platform with this in mind. The deployment steps below are the same regardless of which static host you use.

Step 1 - Upload the app files

Create an account on your chosen static host and create a new site. Most static hosts accept a ZIP archive of your site folder on initial setup - zip the unzipped NaturaList folder with your personalized files and upload it, or use the platform's drag-and-drop interface if available. The app will be live at the assigned URL. It loads correctly but shows no data yet, because no checklist.json exists.

Step 2 - Assign a custom domain or subdomain (optional)

Most platforms let you connect a custom domain in the site settings.

Step 3 - Verify the installation

Open the app URL in a browser. You should see a NaturaList splash screen and the initial Manage screen.

Keeping your site up to date on static hosting

Every update - a new checklist.json, a species photo, an audio file - needs to reach the server somehow. The process depends on what your platform supports.

On platforms with individual file management, you can upload or replace files one at a time through the web file manager or potentially FTP. To update the compiled checklist, download checklist.json from the Manage screen's Publish step and upload it to usercontent/data/ in the file manager. To add or update media files, upload them to the appropriate subfolder of usercontent/ the same way.

On platforms without individual file management, every update requires redeploying the entire site folder. Apply all changes to your local copy first - place the new checklist.json at usercontent/data/, add new images to usercontent/images/, and so on - then redeploy the whole folder. If your platform supports connecting a Git repository, that is a more robust approach: changes pushed to the repository trigger an automatic deployment, and your files are version-controlled rather than living only on your local machine.

---

Option B - PHP-capable server (Apache / Nginx)

On a server that supports PHP, you can enable server-side publishing: editors compile a new checklist in the browser and push it directly to the server without touching any files manually. This is convenient for projects with frequent updates or multiple contributors. If you set up credentials.php in the preparation step above, server-side publishing is already configured and will be active once the app is deployed.

Step 1 - Upload the app files

Using FTP, SFTP, or your hosting panel's file manager, upload the unzipped NaturaList folder to the document root of your domain or subdomain (for example, /var/www/html/ on a typical Apache setup, or public_html/ on shared hosting).

Ensure the folder structure is preserved: index.html and the other app files should sit at the root of the directory being served, not inside a subfolder.

Step 2 - Confirm HTTPS is active

Check that your domain loads over HTTPS. Most hosting providers offer a one-click Let's Encrypt certificate through their control panel. Without HTTPS, the PWA installation prompt and offline capability will not work.

Step 3 - Verify the installation

Open the app URL in a browser and confirm it loads. The inital Manage screen should be displayed.

Keeping your site up to date on PHP hosting

There are two distinct types of update, and they work differently:

Updating the compiled checklist (checklist.json)

If server-side publishing is enabled, this is fully automated: compile your spreadsheet via the Manage screen, choose Server Upload in the Publish step, enter your credentials, and the new checklist.json is placed on the server immediately. No file manager or FTP client needed.

If you have not set up server-side publishing, use the Download option instead and upload the file manually to usercontent/data/checklist.json via FTP, SFTP, or your hosting panel's file manager.

Updating media and content files (usercontent/ folder)

Server-side publishing only handles checklist.json. Any other files your checklist references - species photographs, audio recordings, SVG distribution maps, Markdown description files - must be placed on the server manually. This is true even if server-side publishing is set up and working.

Use FTP, SFTP, or your hosting panel's file manager to upload new or updated files into the appropriate subfolder of usercontent/. For example, a new species photo referenced as images/tree_frog.jpg in your spreadsheet goes to usercontent/images/tree_frog.jpg on the server. The path you write in the spreadsheet is always relative to usercontent/ - make sure the file is there before you compile and publish, otherwise the compiler will report it as missing.

File naming on Linux servers

Web servers on Linux are case-sensitive. Tree_Frog.jpg and tree_frog.jpg are treated as two different files. Use lowercase filenames with no spaces throughout your usercontent/ folder to avoid hard-to-diagnose missing-file errors.

---

Running multiple projects

If you need to host more than one NaturaList checklist, each installation must have its own subdomain (technically different origin) or be on a completely separate site - for example birds.example.com and plants.example.com. Two instances placed in different subdirectories of the same domain (e.g. example.com/birds/ and example.com/plants/) will interfere with each other's PWA service worker cache and must be avoided regardless of which hosting option you choose.

Updating the app to a new version

When a new release of NaturaList is available, updating your installation follows the same process as the initial deployment, with one important exception: do not copy the usercontent/ folder from the downloaded ZIP to your server. The ZIP's usercontent/ folder contains only the default placeholder files that ship with a fresh installation; overwriting your server copy would replace your custom manifest.json and favicon.png. Upload only the remaining app files and folders, leaving your existing usercontent/ directory entirely untouched.

Once the updated app files are in place, it is recommended to recompile your spreadsheet and perform a standard data update to publish a fresh checklist.json. This ensures your data file is generated by the latest version of the compiler and conforms to any format changes introduced in the new release.

After installation: your first data

At this point your NaturaList installation is live but empty. The next step is to prepare your spreadsheet, compile it, and publish the resulting checklist.json. See Workbook Structure to get started building your data, and Publishing Your Project when you are ready to go live.

Try the sample project first

When you open a fresh NaturaList installation, the initial Manage screen offers a button to download a pre-configured template spreadsheet with a simple project. Load it to see the app working end-to-end before you start building your own checklist.