Run Your Own Ark

What does running an Ark involve?

Your Windows computer runs the Arkology application and stores its databases and uploaded media. Caddy receives visitors at your HTTPS domain and passes requests to the application on port 5000. This guide follows the ARK.bat workflow included with this release.

You need a Windows PC that can stay powered on, reliable Internet, a domain you control, and access to your router and DNS settings. Install Python 3.12 with “Add Python to PATH” selected, and Caddy for Windows. Place caddy.exe beside ARK.bat or in a folder on PATH. Caddy and Python are separate downloads, not included in the ZIP.

How do I create an independent installation?

Extract the full program ZIP into a new folder, such as C:\Arkology. Do not run it from inside the ZIP. An independent Ark starts without another community’s databases, resident workbook, credentials, or uploaded files. Keep an existing community’s installation separate; do not delete its data to create a new Ark.

Run ARK.bat and select 12 — First-Time Setup. This installs the bundled Python requirements and supporting market-data packages. If installation reports an error, resolve it before starting the public site. Elections run inside the Python application; the old separate Node election server is not needed.

Which settings do I change?

Open ARK.bat in a text editor. Set ARK_BASE_URL and ARK_PUBLIC_ORIGIN to the same complete address, for example https://your-ark.example. The first supplies links such as password-reset emails; the second sets the public site origin used by the server and Caddy. Use your actual domain, without a trailing path. Start All Servers now inherits these settings.

For the first local setup, set ARK_BIND_HOST=127.0.0.1. Keep ARK_ALLOW_INSECURE_LOCAL=1 for local HTTP access. Caddyfile reads ARK_PUBLIC_ORIGIN when launched through ARK.bat; leave its reverse_proxy target at 127.0.0.1:5000.

Copy secrets.bat.example to secrets.bat and replace the administrator-password placeholder with your own strong password. Follow the character restrictions in that example. Keep secrets.bat private. Email is optional initially; configure the SMTP account and its application password before relying on password-reset emails.

How do I become the first administrator?

Before exposing the site to the Internet, choose 1 — Start Registry Server and open http://127.0.0.1:5000 on the host PC. Use New Resident to create your account. On a genuinely empty installation, the first successful signup passes the reference and immigration checks and receives the #1 Hexarchy position. The signup password requires at least 12 characters.

This shortcut applies only to a new installation. Importing an existing resident database or workbook does not reset its leadership or give the next signup founder privileges. Log in and confirm your Hexarchy access before opening the public ports.

Which ports do I forward?

Reserve a stable LAN IP for the host PC in your router’s DHCP settings. For example, if the reservation is 192.168.1.97, configure the following rules. Use your own host address; this number is only an example.

How do DNS and HTTPS work?

At your domain provider, point an A record for the chosen hostname to your router’s public IPv4 address. The DNS address is the public Internet address, not the PC’s 192.168.x.x LAN address. Add an AAAA record only if you have working public IPv6 routing and firewall access to this server. Update DNS if your public address changes.

Allow inbound TCP 80 and 443 for Caddy in Windows Firewall as well as forwarding them on the router. With the domain resolving correctly and these ports reachable, Caddy obtains and renews HTTPS certificates and redirects HTTP traffic to HTTPS. Do not forward port 5000 publicly. See the linked Caddy HTTPS documentation for the standard requirements.

If your router sits behind another router, both layers need suitable forwarding, or the upstream device needs bridge mode. Carrier-grade NAT can prevent ordinary inbound forwarding even when your router rules are correct. Ask your Internet provider about a public IP or use a separately configured hosting or tunnel arrangement; those alternatives are outside this direct-Caddy setup.

Reference: Caddy automatic HTTPS documentation.

How do I start public and LAN access together?

Stop the initial local server. For LAN access, change ARK_BIND_HOST to 0.0.0.0 and keep ARK_ALLOW_INSECURE_LOCAL=1. Run ARK.bat as Administrator when allowing its LAN firewall rule, then choose 3 — Start All Servers. This opens the Registry and Caddy windows. If the Registry is already running, use 16 — Start Caddy HTTPS instead of starting a duplicate Registry.

Option 3 adds a Windows Firewall rule for TCP 5000 limited to the local subnet. The public Caddy ports still need their own Windows Firewall rules. Keep the Registry and Caddy windows open; the menu does not install them as automatic Windows services.

From the host PC, use http://127.0.0.1:5000. From another PC on your LAN, use http://YOUR-HOST-LAN-IP:5000. Public visitors use https://your-ark.example with no :5000. Explicitly include http:// for the direct LAN address; HTTPS belongs on the domain through Caddy.

How do I confirm it works?

First test the host URL, then the LAN URL from a second device, then the public domain from a phone with Wi-Fi turned off. A public-domain test from inside the same LAN can fail on routers without NAT loopback even when outside access works. Use the direct LAN URL or configure local DNS for that case.

Disable sleep on the host while serving the site and plan how to restart both processes after a reboot. Caddy and the Registry must both be running for public access. Signing in through a LAN IP and through the domain uses separate browser cookies, so you may need to sign in separately on each address.

What should I set up before using real payments?

Founder registration makes the portal usable; it does not create a finished financial configuration. Review the budget workbook, government salaries, benefit eligibility, treasury settings, and every receiving wallet before using money flows. The supplied code and settings can still contain the original Ark’s domain, contact details, and BCH addresses.

In particular, review BCH_SYSTEM_ADDRESS and BCH_BOND_ADDRESS in server.py and the wallet settings in the balance-check and payment scripts. Set receiving addresses for your own projects and corporations. Use wallets you control; never distribute wallet seed phrases or private keys with the website.

Option 5 previews UBI payments without sending BCH. Option 4 runs the monthly workflow and has real financial effects when its apply/send steps are confirmed. Electron Cash must be installed and correctly configured for the UBI sender. Eligibility to receive payments does not itself guarantee a positive UBI amount; the budget, benefits, salary, and taxes determine the calculated payment.

Community taxes use /taxes. Restored online payment forms lock the BCH amount and verify the matching blockchain output before recording payment. Do not substitute a manually calculated BCH amount for the exact payment request. Option 17 applies election results after confirmation; use it only when you intend to change the elected leadership.

How do I back up or update my Ark?

Keep private backups of all .db databases, the resident and budget workbook, secrets.bat, and uploaded-media folders. This project uses both Bulk Data and Bulk_Data, and some older modules have their own media folders. A database-export ZIP contains .db files; it is not a complete media or configuration backup.

For a simple complete backup, stop the Registry and other writers, then copy the entire installation to protected storage. Keep the backup outside any public download folder. Also preserve Caddy’s certificate data if you move the host. Do not publish a copy containing resident records or credentials.

Before updating, make a backup. Stop the Registry, extract the new program ZIP beside ARK.bat, replace program files, preserve your databases and uploads, then restart and test login and the changed pages. Option 18 imports a database backup; it is not the installer for a program-update ZIP. Review ARK.bat after replacement so your own domain, SMTP settings, and bind address remain correct.

How do I connect to Sister Arks?

As the #1 Hexarchy member, open Administration → Sister Arks and choose your local Ark ID. Coordinate distinct IDs with the Arks you connect to; there is no global ID registry or master Ark. Each site keeps its own database.

Add another Ark’s HTTPS domain and Ark ID, then click Connect. Both sites need a compatible Ark API and public reachability. The list shows successful and failed connection times. Connections are configured locally; saving a sister on your site does not automatically add your site to theirs.

The Neighborhood Map’s Ark ID selector fetches a configured sister’s current map in view-only mode. Connect refreshes the shared locations used on the front-page Ark map. The API also exposes public Arkazon listings; private resident records, messages, and orders are not part of those shared datasets.

The host PC cannot open the site

Check the Registry window first. If it shows a Python traceback and has exited, the application is not running. A missing-module error needs the corresponding package or missing program file; restarting the computer does not restore missing files. Run option 12 again for dependency setup, and verify that the full ZIP was extracted together.

If a second server says port 5000 is already in use, keep the working instance or stop it before starting another. Use http://127.0.0.1:5000 on the host. A normal deprecation warning alone is not proof that the server stopped.

The host works but another LAN computer times out

Use the host PC’s current LAN IP and explicitly type http:// before it. Confirm ARK_BIND_HOST=0.0.0.0, restart the Registry after changing it, and allow TCP 5000 from the local subnet in Windows Firewall. Option 3 attempts to add that LAN rule when it has administrator rights.

Check that both devices are on the same trusted LAN. Guest Wi-Fi, client isolation, VPN routes, or a changed DHCP address can prevent one device from reaching another. Router Internet port forwarding is not needed for a direct connection between PCs on the same LAN.

The LAN works but the public domain does not

Check the public DNS A record, any AAAA record, router forwarding for TCP 80 and 443, Windows Firewall, and the Caddy window. Ensure ARK_BASE_URL and ARK_PUBLIC_ORIGIN contain your actual HTTPS domain. Check for another program or router-management feature already using ports 80 or 443.

A “host is not trusted” message usually means the requested host does not match the configured public origin or supported local address. Use the correct domain or direct LAN IP instead of disabling host checks. Certificate failures usually need a DNS or reachability fix; option 15 provides Caddy troubleshooting, but its checks do not replace your router and DNS configuration.

Where can I find the official setup references?

Caddy installation: https://caddyserver.com/docs/install

Caddy automatic HTTPS and port requirements: https://caddyserver.com/docs/automatic-https

Caddy Windows service setup, if you later want automatic startup: https://caddyserver.com/docs/running

Python downloads: https://www.python.org/downloads/

This guide describes the included Windows batch workflow. Router menus vary by manufacturer. Setup checks here were performed against the packaged code; you still need to test your own domain and Internet connection.