Skip to content

STRIDES Deployment

Jump to bottom
Brandon Rose edited this page Jun 23, 2025 · 1 revision

Biome STRIDES Management Guide

Overview

Biome is managed as a systemd service under the name biome.service. This service is responsible for running the Beaker kernel server process, which is started using a custom Python installation located at /opt/biome-python. The service is configured to write its logs to a dedicated log file for easy troubleshooting and monitoring.

Note: The biome repository found in the home directory (~/biome) is the source code used to install or build the Biome service and its dependencies.

Service Location

  • Service file: /etc/systemd/system/biome.service
  • ExecStart: python3.12 -m beaker_kernel.service.server
  • Python binary: /opt/biome-python/bin/python3.12 (custom installation)
  • User: Typically runs as root or a dedicated user (e.g., beaker)
  • Source repo: /home/ubuntu/biome (for reference or development)
  • Beaker install: /opt/biome-python/bin/beaker
  • Beaker environment: /root/env.biome (includes BEAKER_APP configurations)

Log Location

  • Log file: /var/log/beaker.log
  • The service is configured to append all standard output to this file via the StandardOutput=append:/var/log/beaker.log directive in the service file.

To view the logs in real time:

tail -f /var/log/beaker.log

Logging Methods

Application Logs vs Systemd Logs

Due to the StandardOutput=append:/var/log/beaker.log configuration, there are two different types of logs:

  • tail -f /var/log/beaker.log - Shows the actual application output (Beaker server logs, API requests, etc.)
  • journalctl -u biome.service - Shows only systemd's own messages about the service (start/stop events, resource usage, etc.)

Example Output Differences

Application logs (tail -f /var/log/beaker.log):

[I 2025-06-23 13:07:40.481 BeakerServerApp] 200 GET /api (127.0.0.1) 0.37ms userid=none
[I 2025-06-23 13:07:59.710 BeakerServerApp] 200 GET /api (127.0.0.1) 0.38ms userid=none

Systemd logs (journalctl -u biome.service):

Jun 17 06:20:04 ip-172-31-7-226 systemd[1]: Started biome.service - Biome service.
Jun 17 06:20:04 ip-172-31-7-226 systemd[1]: biome.service: Consumed 33.088s CPU time, 372.3M memory peak

Editing the Service

To change how the service is started or where it logs:

  1. Open the service file for editing: 
    sudo nano /etc/systemd/system/biome.service
  2. Make your changes (e.g., modify ExecStart, change log file path, etc.).
  3. Save and exit the editor.
  4. Reload systemd to pick up changes: 
    sudo systemctl daemon-reload
  5. Restart the service: 
    sudo systemctl restart biome.service

Useful Commands

  • Check service status: 
    systemctl status biome.service
  • View systemd logs (service start/stop events): 
    journalctl -u biome.service
  • View systemd logs in real-time: 
    journalctl -u biome.service -f
  • View application logs (file): 
    tail -f /var/log/beaker.log
  • Edit the service file: 
    sudo nano /etc/systemd/system/biome.service
  • Reload systemd after editing: 
    sudo systemctl daemon-reload
  • Restart the service: 
    sudo systemctl restart biome.service

Troubleshooting

  • If the service does not start, check /var/log/beaker.log for errors.
  • Ensure the service file syntax is correct and that the specified Python path and module exist (especially /opt/biome-python/bin/python3.12).
  • After any changes to the service file, always reload systemd and restart the service.
  • For development or debugging, refer to the ~/biome repository for source code and installation scripts.

Users

Biome is built on Beaker (Jupyter) and uses a multi-user architecture for security and isolation.

  • Systemd Service User:
    The main Biome service (biome.service) runs as root (see User=root in the service file).

  • Kernel Management User:
    The beaker user is used to launch and manage kernel processes (beaker_kernel.kernel). This user is a system user and does not have a login shell.

  • Notebook Kernel User:
    When you execute code in a Biome notebook, the kernel process (which runs your code) is started as the restricted user user.

    • For example, running !whoami inside a notebook will return user.
    • This user is configured with /usr/sbin/nologin to prevent interactive logins and is used only for code execution.

Systemd users vs. inside Docker

In both a systemd and docker setup, the agent needs to be able to write to the filesystem. It's important to note that the user for this in docker differs from on the STRIDES server (jupyter vs. beaker) and this may cause some complications.

Role/Function Systemd/Server Docker
Main service process root root
Kernel manager/agent (BEAKER_AGENT_USER) beaker jupyter
Notebook code runner (BEAKER_SUBKERNEL_USER) user user

Clone this wiki locally