11. Advanced Networking and Maintenance

This chapter is for the server’s owner and admins. It covers the server’s network settings and day-to-day maintenance. Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel. The Network group has the TURN Server tab, where you set up the built-in TURN relay. The first tab of the Server Settings group, Dashboard, shows statistics on the server’s scale. Further down the Dashboard tab, from top to bottom, are the Backup, Orphan Files, Server Update, and Server Actions sections, which this chapter also covers. What this chapter describes is exactly the same for the owner and for admins.

11.1 Built-in TURN Server

Opening the Tab and Its Layout

Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, then click the TURN Server tab in the Network group. The title at the top of the tab is also TURN Server.

From top to bottom, the tab contains: the environment variable override notice (shown only when the server points to an external TURN), the enable switch and status, the TURN port, the address mode, running a diagnostic, and the firewall note.

If this server already points to an external TURN through an environment variable, a notice appears at the very top of the tab. It reads exactly: “TURN is configured via environment variables (TURN_URL). Disable TURN_URL to use the built-in TURN server.” While this notice is shown, the enable switch below can’t be clicked. To use the built-in TURN instead, you first have to remove the TURN_URL environment variable.

Enable Built-in TURN Server (Switch + Status)

Enable Built-in TURN Server is the first section of the tab, with a one-line description beside it: “Run a TURN relay server to help users behind strict NATs (VPN, corporate networks) connect to voice channels.”

This section has a switch. Clicking it changes the setting and applies it immediately; there’s no need to save. When the environment variable override described above is in effect, this switch can’t be clicked.

Below the switch is the status line: Status, followed by a dot. While the server is running TURN, it shows a green light and Running. When TURN is stopped, it shows a gray light and Stopped.

TURN Port

TURN Port sets the port that TURN uses externally, with a one-line description beside it: “UDP and TCP port for the TURN server. Must be open in your firewall.”

This is a number box that shows 3478 by default. After you change it, click Save next to it to save the new port.

Address Mode (Static IP / Dynamic DNS)

Address Mode tells TURN how to get this server’s public address. Below it are two side-by-side buttons, and you choose one: Static IP or Dynamic DNS (DDNS). Whichever you choose, the matching settings area appears below.

When you switch to Static IP, Public IP Address appears below, with a one-line description: “The public IP address of this server.” This is a text box, and its hint text is 203.0.113.45. Next to it is the Auto-detect button. Clicking it tries to fill in the detected public IP, and the button shows that it’s busy while detecting. Once you’ve confirmed the address, click Save to save it.

When you switch to Dynamic DNS (DDNS), DDNS Hostname appears below instead, with a one-line description: “Your DDNS hostname (e.g. myserver.duckdns.org). The server will periodically resolve it.” This is a text box, and its hint text is myserver.duckdns.org. After you fill it in, click Save to save the hostname. From then on, the server resolves it periodically to get the latest address.

Run Diagnostic

Once the address is set, you can click Run Diagnostic to run an internal self-test. You can click this button only when TURN is already enabled; until then, it can’t be clicked.

If the test succeeds, it shows “TURN server is running internally.” If it fails, it shows “TURN diagnostic failed”, followed by details of the failure.

Below the button is an important note. It reads exactly: “This is an internal self-test only. It does NOT verify external connectivity. To confirm TURN works for real users, test with a VPN or from an external network.” In other words, a successful diagnostic only means that TURN itself runs on the server’s end. It doesn’t mean that outside users can definitely connect. To really confirm it, test a voice connection once from an external network or over a VPN.

Firewall Note

At the very bottom of the tab is a note box that reminds you to open the ports. Its text includes the port you currently have set (default 3478): “Make sure UDP and TCP port 3478 are open in your firewall and forwarded to this server if behind a router (TCP is a fallback for clients on UDP-blocked networks).”

11.2 Dashboard (Statistics)

Opening and Refreshing

Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, then click Dashboard, the first tab in the Server Settings group. The title at the top of the tab is Server Dashboard.

When you open this tab, the statistics load once without you having to do anything. On the right is a Refresh button. To update the numbers, click it to fetch them again.

Statistics Cards

The top of the tab is a grid of statistics cards. Each card shows one number, and the values come from the server. While the statistics are loading, the grid isn’t shown yet, and a spinning loading indicator appears in the center of the screen. The grid appears once loading finishes. After loading, if a card’s value is missing, that card shows —.

The statistics cards you’ll mainly use are:

• Total Users — the total number of users who have registered on this server
• Online Users — the number of users who are currently online
• Banned Users — the number of users who have been banned
• Total Messages — the total number of messages across the server
• Today Messages — the number of messages so far today
• Total Channels — the number of channels across the server
• Database Size — the space the database currently takes up
• Uploads Size — the total space taken up by files that members have uploaded
• IO Apps Size — the total space taken up by IO Apps
• Pages size — the total space taken up by web page content
• Memory Usage — the server’s current memory usage

The grid also has a Goroutines card, which shows the number of the server’s internal threads. It’s a fairly technical metric, and this manual doesn’t go into it.

The disk and size figures among them (Database Size, Uploads Size, IO Apps Size, Pages size, and Memory Usage) are automatically converted to readable units and shown as B, KB, MB, or GB, depending on their magnitude. These cards show the numbers from the moment you refreshed or first opened the tab. To see the current state, click Refresh again.

11.3 Backup

Scroll down the Dashboard tab: the first section below the statistics cards is Backup. You use it to create and download database backups. It has a one-line description beside it: “Create and download a database backup.”

Click Create Backup to create a backup. The button shows that it’s busy while the backup is being created. When it’s done, “Backup created successfully!” briefly appears next to it.

Once the server has backups, a backup list area appears below:

• A drop-down menu lists all existing backups. Each option shows “backup file name (file size)”, with the size automatically converted to readable units.
• Download Backup downloads the currently selected backup. It can’t be clicked until you select a backup.
• Delete (red) removes the currently selected backup. It can’t be clicked until you select a backup, and it shows that it’s busy while deleting.

After you select a backup, two lines of details appear below: Size is the backup’s file size (in readable units), and Created at is the date and time it was created.

11.4 Orphan Files

Scroll further down the Dashboard tab: the section after Backup is Orphan Files. You use it to find files that were uploaded but are no longer referenced anywhere. Its one-line description reads, word for word: “Scan for uploaded files that nothing references — no message, note, whiteboard, page, user, server setting, or other server asset (stickers, sounds, badges, themes). Recently uploaded files are skipped: they may still be on their way into a message.”

Click Scan to start scanning. The button shows that it’s busy while scanning. When the scan finishes, what appears depends on the result:

• If orphan files are found, a red Delete All ({count}) button appears. The number in parentheses is how many were found.
• If no orphan files are found, a green “No orphan files found.” appears.

When files are found, a list appears below. Its header reads, word for word, “{count} orphan file(s) found”, where {count} is the number of files, followed by the total size of these files (in readable units). Each row of the list shows the file name on the left and that file’s size on the right. Once you’ve checked the list, you can click Delete All ({count}) to clear them all at once and free up disk space.

Why the Scan Finds Fewer Files Than Expected

Files that were recently uploaded and haven’t been sent yet aren’t referenced by anything, but they aren’t orphans. So the scan deliberately skips files that are too new: ordinary files aren’t listed for one hour after upload. Files that the server knows were “uploaded but not yet picked up by any message” aren’t listed for 24 hours, and their thumbnails are skipped along with them.

This is usually why “the scan found fewer files than I expected”. It doesn’t mean the scan is broken.

When the Scan Stops

To decide what counts as an orphan, the scan first has to read every source of references that are “still in use”. If any one of them can’t be read, the whole scan stops and lists no files at all. A red banner shows which read failed and the underlying reason, word for word: “Scan stopped: could not read “{source}” ({reason}). Nothing is listed until it can be read, so that files still in use are not mistaken for orphans.”

This is by design: “couldn’t read it” and “not referenced” must not give the same answer. Otherwise, a whole category of assets that are still in use would be listed as deletable, and the delete step doesn’t check again. When you see this banner, don’t rush to retry the delete. First deal with the source that failed to read.

What the Delete Reports

After you click Delete All ({count}), the server deletes the files one by one and reports what it actually did:

• “Deleted {count} file(s), freed {size}.” — the number of files actually deleted and the space freed.
• “{count} file(s) kept because they are too recent — they may still be on their way into a message.” — appears only when files were actually kept.
• “{count} file name(s) failed the safety check and were skipped.” — likewise appears only when this actually happened.

After the delete finishes, the list is checked with the server once more instead of being cleared outright (files that were kept are still there, and clearing the list would hide them). While the delete is in progress, the Scan button is disabled so that the two don’t interfere with each other.

If something goes wrong partway through the delete, the banner says “The delete did not complete”, not “no files changed”. The server deletes files one at a time and has no way to roll back the whole batch, so if the connection drops, the client can’t know how many files were actually deleted. After an error, the list is also checked with the server once more. When this check succeeds, the banner adds “The file list has been re-checked against the server.”, and the list below shows the actual state. If the banner doesn’t add this sentence, scan again to see the actual state.

11.5 Server Update

Scroll further down the Dashboard tab: the section after Orphan Files is Server Update, with a download icon to the left of its title. You use it to see the current version, decide whether to receive pre-releases, and download and apply a new version when one is available.

Current Version

The top row is Current Version, with this server’s current version string on the right. Before it loads, it shows —.

Receive Pre-release Updates

Below that is a card, Receive Pre-release Updates, with a one-line description beside it: “When enabled, update checks will also include pre-release versions. Pre-releases may contain incomplete or unstable features.”

It has a switch that changes as soon as you click it. When you turn it on, a yellow reminder appears below it. It reads exactly: “⚠ Pre-release versions may contain unfinished features or known issues. Recommended for testing only.”

What this switch actually decides is “which version an update check offers”:

• On — picks the one with the highest version number from all eligible versions, pre-releases included.
• Off — looks only at stable releases and offers the newest of them.

The switch is off by default. Each time you change it, the update area goes back to its not-yet-checked state. Click Check for Update again to check with the new setting.

Note that whether there’s “a new version” depends on whether the executable itself has changed, not on which version number is higher. This has three practical results:

• When the same version number has been released again (the version number stays the same, but the executable is rebuilt), an update still appears here — it really is a different executable.
• If you’re running a pre-release with the switch off, Check for Update offers the latest stable release, even if its version number is lower than the current one. This is how you switch from a pre-release back to a stable release: turn off the switch, click Check for Update, and then download and apply it with the steps below.
• Conversely, if you’re running a stable release and turn the switch on, Check for Update offers an eligible pre-release whenever there is one newer than the latest stable release.

If this server runs a pre-release that you downloaded yourself (you set it up with a pre-release from the start, or switched to one manually later; you can download one from the Version menu on the website’s download page, see Quick Self-Host Guide §4.2), remember to turn this switch on as well. That way, Check for Update keeps offering new pre-releases.

Checking for and Applying Updates

After you click Check for Update, the update area shows different content depending on the result. While it checks, it first shows Checking….

If the server is already up to date, it shows Up to date with a check mark, followed by Last checked and the time.

If this server runs in a container, the update area instead shows Managed by Docker with a whale icon, along with an explanation: “This server runs in a container, so in-app self-update is disabled. Update by pulling a new image and recreating the container — your data persists in the volume.” Below that is a command that you can select in full and copy:

docker compose pull && docker compose up -d

Update a server that runs in a container with this command: pull the new version and recreate the container. Your existing data is kept and isn’t lost.

If an update is available, a “New version available!” block with an up arrow appears. It lists Latest Version, File Size, and Published, along with release notes that you can expand to read. To update, click Download Update. As it runs, you see the progress and the time remaining for stages such as Downloading and Verifying.

The downloaded file is automatically verified by comparing its SHA256 hash. If automatic verification fails, “SHA256 automatic verification failed” appears with a warning sign, and the hint reads: “This may be a transient network issue or SHA256SUMS.txt is not uploaded yet. Please open the GitHub Release page and manually compare the hashes below. If they match the release page, you may choose to skip verification and apply.” You can then click the Open GitHub Release link and check the hashes manually on that page. If they match, click the red I verified manually, skip and apply to continue. Or click Discard staged update or Cancel to abandon this update.

When the download and verification are complete, it shows Download complete, verified with a check mark, and a yellow Apply Update button appears next to it. Clicking it opens a confirmation step, with a warning in a yellow box that reads exactly: “This will disconnect all users and restart the server. Are you sure?” The confirm button is the red Yes, Apply Update, and there is also Cancel. While the update is being applied, it shows Updating server….

Apply updates during off-peak hours, when fewer users are online. Before you apply one, always go to the Backup section above and click Create Backup (§11.3).

On Linux, after you click Yes, Apply Update, the server switches to the new version and restarts, and all users’ connections are interrupted in the meantime. For a server that runs as a systemd service, systemd handles the restart, and the service configuration must use Restart=always (for the service configuration, see Quick Self-Host Guide §4.5; if the server doesn’t come back after applying, see §12.2). Once the new version starts, every member receives a System Update notification: “Updated from {from} to {to}”.

Where Updates Are Downloaded From

For a server set up as a single executable, when you click Check for Update and Download Update, the server connects to HakoSpace’s software distribution source, dl.hakospace.com, to look up and download the new version. When that source is unavailable, it automatically connects to GitHub instead. The server makes outbound connections for updates only when you click these two buttons. If a firewall restricts the server’s outbound connections, see §12.2 for the domains to allow.

11.6 Server Actions (Restart)

At the very bottom of the Dashboard tab is Server Actions, with a one-line description beside it: “Execute server management operations. The server will be temporarily unavailable during restart.”

The action currently offered is a restart. Its button is the yellow Restart, and it uses a two-step confirmation to prevent accidental clicks:

• The first click on Restart opens a confirmation step, and “Are you sure?” appears next to it.
• The confirmation step shows a red Confirm button and a Cancel button. The restart runs only when you click Confirm. Click Cancel to back out. The button shows that it’s busy while the restart runs.

On Linux, after you click Confirm, the server restarts and is temporarily unavailable in the meantime, so do this when fewer users are online. For a server that runs as a systemd service, systemd handles the restart, and the service configuration must use Restart=always (see Quick Self-Host Guide §4.5).