3.16.1 Service control ¶

sudo systemctl status   ownsona.service
sudo systemctl restart  ownsona.service     # required after any application.ini change
sudo systemctl stop     ownsona.service
sudo systemctl start    ownsona.service
journalctl -u ownsona.service -f             # live application + Tomcat logs

3.16.2 Code change ⇒ deploy ¶

cd /home/ownsona/ownsona
./bld -v build && ./bld war
cp work/Kiss.war /home/ownsona/tomcat/webapps/ROOT.war
# autoDeploy redeploys in ~10 s; no service restart needed for code changes.

application.ini is read once at servlet load, so editing it requires a fresh build (so the new ini lands in the WAR) followed by redeploy or service restart.

3.16.3 Backup control ¶

sudo systemctl list-timers ownsona-backup.timer       # next run
sudo systemctl start ownsona-backup.service           # one-shot now
sudo tail -f /var/log/ownsona-backup.log              # last run + history

3.16.4 Log retention summary ¶

3.16.5 Rotating login credentials ¶

Change OWNSONA_LOGIN_PASSWORD in src/main/backend/application.ini, rebuild the WAR (./bld -v build && ./bld war), and redeploy. Issued access tokens remain valid until their TTL expires — the password is only consulted on the AS login page. To invalidate every existing token immediately, also delete the AS state file (the path you set in OAuthAsIniFile, or WEB-INF/backend/oauth.ini if you kept the default) before restart: the AS will mint a new signing key and every previously-issued JWT will fail signature verification. Registered clients will have to re-register and re-authorize, which for typical MCP clients means the user redoes the login + Allow flow.

3.16.6 Rotating the AS signing key only ¶

To rotate the JWT signing key without forcing a re-registration of every client: stop the service, edit the AS state file (the path you set in OAuthAsIniFile, or WEB-INF/backend/oauth.ini if you kept the default) and remove the [keys] section (and any kid references in [client.*] entries you wish to keep), restart. The AS will generate a fresh key on first OAuth request; existing access tokens become invalid. Clients with refresh tokens issued before the rotation also lose them — refresh tokens are signed with the same key.

3.16.7 Top common failure modes ¶

• journalctl -u ownsona.service shows BindException: Permission denied: the service couldn’t bind 80/443. systemd’s AmbientCapabilities is missing from ownsona.service, or the service’s User= was changed and the override no longer applies.
• MCP returns EMBEDDING_ERROR with insufficient_quota: the OpenAI account is out of credit. Top up; auth, DB, listing, and text search keep working.
• Every /mcp request returns 401: the client is sending no token, an expired one, or one signed by a different AS key than the one in the current AS state file. The WWW-Authenticate header on the 401 names the resource-metadata URL the client should use to re-discover the AS. If every client started failing all at once right after a redeploy and you kept the default oauth.ini location in the WAR tree, this is the redeploy clobbering the state file — set OAuthAsIniFile to an absolute path outside the webapp.
• /oauth/authorize returns 500 with “UserAuthenticator not registered”: KissInit.groovy did not register OwnsonaUserAuthenticator. Check that the WAR contains both WEB-INF/classes/ai/ownsona/oauth/OwnsonaUserAuthenticator.class and a KissInit.groovy that wires it via AsExtensions.setUserAuthenticator(...).
• AS cannot persist state: the directory containing the AS state file is not writable by the JVM user. Run ls -ld dirname-of-OAuthAsIniFile and confirm it is owned by the service user.
• First request after deploy is slow / 404: Tomcat is still redeploying the WAR; ~10 s window with autoDeploy="true".