Linux: From Extraction to First Login

This page is for Linux users installing AKStream.Next for the first time. The goal is to install the Release as a systemd service, open the initial configuration page, and know where to look when problems occur.

flowchart LR
    A[Check architecture and package] --> B[Extract to fixed directory]
    B --> C[Run installer]
    C --> D[systemd manages services]
    D --> E[Open port 5800 and finish setup]

1. Confirm Machine Architecture

uname -m

Do not use the x64 MediaServer on ARM64, and do not use QEMU emulation as a production solution.

2. Prepare Basic Dependencies

The Release requires the .NET 7 ASP.NET Core Runtime. MySQL must be reachable before the initial configuration is completed; FFmpeg is used for file tasks such as clipping, snapshotting, or transcoding.

For Ubuntu/Debian, you can first execute:

sudo apt-get update
sudo apt-get install -y curl ffmpeg
dotnet --list-runtimes
ffmpeg -version

If the runtime is missing, you can add --install-runtime to the installation command, and the script will handle it via the official Microsoft installation entry. The current project target remains net7.0; migrating to a supported .NET version is a separate upgrade task.

3. Verify and Extract

sha256sum -c SHA256SUMS.txt --ignore-missing
tar -xzf AKStream.Next-<version>-linux-x64.tar.gz
cd AKStream.Next-<version>-linux-x64

For ARM64, replace the filename with linux-arm64. First, read the Package Structure and confirm that AKStream.Next/, NodeAgent/, and Deploy/linux/ exist.

4. View Commands Supported by the Current Script

./Deploy/linux/akstream-next.sh --help

Do not copy parameters from other versions; refer to the help output of the script in the current package.

5. Installation

Execute the following in the root directory of the extracted package:

sudo ./Deploy/linux/akstream-next.sh install \
  --package-dir "$PWD"

The script checks CPU/RID, the .NET Runtime, FFmpeg, and the chosen media-service source, then installs the main service and NodeAgent as root systemd units with the managed Nginx entry. Whether MediaServer is bundled depends on the release asset; if absent, choose an existing node or another supported preparation path in the installer and first setup. It does not create dedicated service accounts. Default locations:

• Program: /opt/AKStream.Next
• Main Configuration: /etc/akstream-next/Config/akstream.next.json
• Initial Installation Code: /etc/akstream-next/Config/.akstream-next-setup-token
• Agent Data: /var/lib/akstream-next-agent

Use --install-dir if you need to customize the program directory. The configuration directory is still managed fixedly by the script; do not mix the program, keys, and recordings in a single temporary directory.

6. Open the Initial Configuration Page

A fresh installation allows for the temporary absence of akstream.next.json. The script will start a restricted initial configuration mode and output the access address.

sudo cat /etc/akstream-next/Config/.akstream-next-setup-token
curl -fsS http://127.0.0.1:5800/health

Open the following in a browser that can access the server:

http://<server-ip>:5800/

Enter the installation code and follow the 10 steps according to Complete Initial Configuration. Once completed, the main process exits proactively and the independent NodeAgent restarts it through the fixed systemd unit allowlist. This is normal; the main unit itself remains Restart=no.

7. Check Service Status

./Deploy/linux/akstream-next.sh status
systemctl status akstream-next.service --no-pager
systemctl status akstream-next-agent.service --no-pager

status simultaneously checks the main service, NodeAgent, and /health. It is not enough for systemd to show "active"; the health interface must also succeed.

8. View Logs

sudo journalctl -u akstream-next.service -n 200 --no-pager
sudo journalctl -u akstream-next-agent.service -n 200 --no-pager
sudo journalctl -u akstream-next.service -f

First record the time of the failure, then save the logs for the main service, Agent, MediaServer, and Nginx within the same time period. Do not copy only the last line of the exception.

9. Common Lifecycle Commands

After installation, use akn from any directory:

akn status
sudo akn start
sudo akn restart
sudo akn stop

verify-recovery forcibly terminates the main process and verifies that NodeAgent can still recover it through the fixed Provider after the control connection is lost. It causes a short interruption and should only be executed during a maintenance window:

sudo akn verify-recovery

10. Upgrade and Uninstallation

To upgrade, extract the new package and execute install --package-dir "$PWD" within the new package. Back up configurations, databases, security directories, and recordings first, and confirm the database migration and rollback plan for the new version.

Interactive uninstallation asks whether to retain data or perform a complete cleanup, then confirms complete cleanup again:

sudo akn uninstall

sudo akn uninstall --purge --yes is reserved for explicitly authorized unattended cleanup. It deletes configuration, tokens, runtime data, and managed Nginx entries; it is not intended for routine fault recovery.

Next steps: Management Command Quick Reference and Complete Initial Configuration.

Third-party dependency sources

The installer prefers verified Chinese mirrors. Debian/Ubuntu (including ARM Ubuntu Ports) and mapped RPM repositories use temporary source settings and retain distribution signature checks; failure falls back to the original official/configured sources. macOS uses USTC Homebrew API and Bottles for FFmpeg, databases, Nginx and build dependencies, with an official-source fallback and no permanent environment changes. The required ASP.NET Core Runtime currently has no verified stable Chinese mirror in this installer and uses Microsoft. Source selection does not change architecture, runtime type or version requirements.