Running tuna as a Service

Background running is useful if you want to establish permanent external access to services or control panels on a remote computer.

Creating and Managing Services

Creating and managing services is available on all supported platforms. To create and work with services, use the tuna service or tuna svc command.

note

You can view all current flags, hints, and examples by calling help:

tuna service --help
tuna service install --help
tuna service start --help
tuna service restart --help
tuna service stop --help
tuna service uninstall --help

Creating a Service

info

In Windows, you need to run commands in PowerShell as administrator, in Linux and FreeBSD you will need sudo or root user. In macOS, the service is created under the current user and no privileges are needed.

The tuna service install command indicates that a new service needs to be registered. You can create multiple services with different names by passing the name through the --name flag or the TUNA_SERVICE_NAME environment variable, default is tuna. After -- the command that will be run in the service is described.

tuna service install -- tuna --config=C:\Users\Administrator\AppData\Local\tuna\tuna.yml http 8080 --subdomain=web

In the example above, the full path to the configuration file is explicitly passed, this may be necessary because the service is created from the administrator account, while the file with the token is located in the current user's profile. This will most likely be required in Windows, Linux and FreeBSD and will not be required in macOS. You can also pass the token explicitly in the arguments:

tuna service install --name=tuna-web -- tuna http 8080 --subdomain=web --token=<tt_your_token>

For greater security in Linux, FreeBSD and macOS, the token will be cut from the startup arguments and passed as an environment variable, so you won't see the token in the process list.

Attention

Since in Windows, Linux and FreeBSD the service is created from a privileged user, by default the process will also run from it, for security reasons it is not recommended to run tuna from a privileged user. Therefore, you can explicitly specify the user from whose name the process will run using the --user flag or the TUNA_SERVICE_INSTALL_USER environment variable. In Windows, you may also need to pass the user password using the --password flag or the TUNA_SERVICE_INSTALL_PASSWORD environment variable.

tuna service install --user=ubuntu -- tuna http 8080 --subdomain=web --token=<tt_your_token>

Starting a Service

Starting is done with the tuna service start command.

Example with name passing:

tuna service start --name=tuna-web

Restarting a Service

Restarting is done with the tuna service restart command.

Example with name passing:

tuna service restart --name=tuna-web

Checking Service Status

Status checking is done with the tuna service status command.

Example with name passing:

tuna service status --name=tuna-web

Stopping a Service

Stopping is done with the tuna service stop command.

Example with name passing:

tuna service stop --name=tuna-web

Removing a Service

Removal is done with the tuna service uninstall command.

Example with name passing:

tuna service uninstall --name=tuna-web

Debugging and Troubleshooting

If the service is not working or is working incorrectly, first you need to check the service logs. Tuna provides only a high-level wrapper for creating and running a service, the debugging method will depend on your system.

Windows

To manage the tuna service in Windows, you can use the Services tool. In the service list, find tuna (or the name of your service). Right-click on the service and select the desired action: Start, Stop, or Restart.

To view tuna service logs, you can use the Event Viewer tool or PowerShell. In Event Viewer, open Windows Logs > Application or System to find logs related to your service.

Viewing logs via PowerShell:

Get-EventLog -LogName System -Source tuna

macOS

When creating a service, a <service_name>.plist file will be created in the ~/Library/LaunchAgents directory. To manage the service, use the launchctl command.

To view logs, open the Console application from Applications > Utilities, go to the system.log section or use the search bar to search for keywords such as tuna.

Viewing logs in terminal:

log show --predicate 'process == "tuna"' --info

Linux

note

Debugging is described only for systemd, if you are using a distribution with sysvinit or openrc we assume that you are an experienced Linux user and can debug the service yourself.

When creating a service, a <service_name>.service file will be created in the /etc/systemd/system directory. To manage the service, use the systemctl command.

Viewing logs:

sudo journalctl -xe -f -u <service_name>

FreeBSD

When creating a service, a <service_name> file will be created in the /usr/local/etc/rc.d/ directory. To manage the service, use the service command.

By default, stdout and stderr should be collected in the system log.

Running a Service in Docker Compose

As an alternative, you can use running the service with Docker Compose

Create a compose.yml file with the service description:

---
name: tuna
services:
  web:
    image: yuccastream/tuna:latest
    command: http 3000 --subdomain=web
    restart: always
    network_mode: "host"
    environment:
      - TUNA_TOKEN=<your_token>

Important

The network_mode: "host" option, equivalent to --net=host, is only available by default in Linux. To make it work in Windows and macOS, you need to enable this beta feature in Docker Desktop. To enable this feature, go to the Features in development tab in Settings, then select Enable host networking.

Starting the service:

docker compose up -d

Stopping the service:

docker compose down -v

Viewing logs:

docker compose -f web