1 FAQ and Troubleshooting

Access and Runtime

Q: The service is running but the page won't open?

ss -tlnp | grep lynx-board        # actual listening port (may have auto-switched)
cat /opt/lynx-board/data/port.json
curl -s http://localhost:<port>/api/admin/check   # does the local API respond
sudo ufw status                   # does the firewall allow the port

Confirm the port and device IP are correct; behind a reverse proxy, check the forwarded target port.

Q: The service keeps restarting?

journalctl -u lynx-board -n 100 --no-pager

Common causes: ports exhausted, data-directory permission problems, or disk space running out. Locate the error in the logs and fix accordingly.

Q: The page says "login expired, please log in again"?
Login lasts 7 days by default — just log in again; to extend it, see the login validity adjustment under "Access Port and Service Management".

Q: Is open registration safe?
It lets teams join on their own, but anyone reaching the address can register. Restrict network sources (firewall, secure proxy) and always serve externally over HTTPS.

Accounts and Data

Q: What if a password is forgotten?

• Member forgot: an administrator resets it under "Account Management".
• Administrator forgot: there is no self-service recovery — move the data file away, re-initialize the administrator, then import the board backup:

sudo systemctl stop lynx-board
sudo mv /opt/lynx-board/data/lynx-board.db /var/backups/lynx-board-forgot-$(date +%F).db
sudo systemctl start lynx-board

Starting with an empty database, visiting the device address shows the "create administrator" page again; then load the previously exported board backup via "Import JSON". Note: member accounts and mail reminder settings are not included in board exports — rebuild them afterwards.

Q: Where is data stored, and how do I back it up?
Everything lives in the single file /opt/lynx-board/data/lynx-board.db; copying it after stopping the service is a complete backup — restore by putting it back and restarting, see "Data Backup and Upgrades".

Q: How do I migrate data to a new device?
Once the new device is ready, stop the service, copy the data file into /opt/lynx-board/data/, start and verify by logging in.

Q: The data file is corrupt or startup reports a database error?
Stop the service, replace the data file with the latest backup and restart; with no backup, move the broken file away — the service starts empty and "Import JSON" restores the boards.

Q: Is a port.json in data/ normal?
Yes — it records the auto-selected listening port, maintained by the program; no manual editing needed.

Upgrade and Migration

Q: Do upgrades lose data or configuration?
No. Upgrades explicitly preserve the data directory and /etc/lynx-board/env; boards, member accounts, login states and reminder settings all carry over.

Q: What if an upgrade fails?
Any failed check rolls back automatically to the pre-upgrade version with the service still running; inspect the cause with journalctl -u lynx-board -n 50 --no-pager, fix it and reinstall the new version.

Q: Do I need to reconfigure the port and login validity after upgrading?
No — those settings survive upgrades and stay unchanged unless you modify them.

Q: Does data survive uninstalling?
sudo dpkg -r lynx-board removes only the program, keeping data and configuration — reinstall to continue; sudo dpkg -P lynx-board deletes data too — back up first.

Q: How to recover after a system reinstall?
The program is redeployed by production, then restore the data file per "Data Backup and Upgrades", restart and log in; for a replaced device, follow "migrating to a new device".