Soft Serve

After creating your service file, use the following commands to reload the daemon, enable the service to start on boot, and start the service immediately.

# Reload systemd daemon
sudo systemctl daemon-reload

# Enable Soft Serve to start on-boot
sudo systemctl enable soft-serve.service

# Start Soft Serve now!!
sudo systemctl start soft-serve.service

Since Soft Serve uses SSH for authentication, you can generate access tokens to use as basic auth credentials for HTTP(s) or git:// connections. Use the token as the username in the URL.

Commands:

• token create '<name>': Create a token.
• token create --expires-in <duration> '<name>': Create a token with an expiration (e.g., 1y).

To avoid specifying the hostname, port, and identity file for every command, add an entry to your ~/.ssh/config file. This also allows git to use the shorthand hostname for cloning and pushing.

Example configuration for a local instance:

Host soft
  HostName localhost
  Port 23231
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

You can browse repositories using the Soft Serve TUI over SSH. To connect to a local instance, use the following command:

ssh localhost -p 23231

To link directly to a specific repository within the TUI, use the -t flag:

ssh -p 23231 localhost -t soft-serve

Note: Copying text (like clone commands) to your clipboard over SSH requires a terminal that supports OSC52.

To run Soft Serve manually via Systemd, create a service file at /etc/systemd/system/soft-serve.service.

Note that the following example assumes running as root. Ensure ExecStart points to your soft-serve binary location and SOFT_SERVE_DATA_PATH is correctly set.

[Unit]
Description=Soft Serve git server 🍦
Documentation=https://github.com/charmbracelet/soft-serve
Requires=network-online.target
After=network-online.target

[Service]
Type=simple
Restart=always
RestartSec=1
ExecStart=/usr/bin/soft serve
Environment=SOFT_SERVE_DATA_PATH=/var/local/lib/soft-serve
EnvironmentFile=-/etc/soft-serve.conf
WorkingDirectory=/var/local/lib/soft-serve

[Install]
WantedBy=multi-user.target

You can view the contents of a specific file within a repository using the repo blob command.

Options:

• -c: Enable syntax coloring.
• -l: Print line numbers.
• --raw: Print raw file contents (useful for binary data).

If you are not using the pre-packaged deb/rpm versions, you can manage Soft Serve as a Systemd service.

1. Prepare the data directory: Create the directory where Soft Serve will store its data (e.g., /var/local/lib/soft-serve).
2. Configure environment variables: Use the SOFT_SERVE_DATA_PATH environment variable to point to your data directory.
3. Create a configuration file: You can use an environment file (e.g., /etc/soft-serve.conf) to override settings. Settings defined in this file will override the config.yaml located in the data path. Specifically, keys defined in SOFT_SERVE_INITIAL_ADMIN_KEYS will be merged with the initial_admin_keys from the data path's config.yaml.

You can interact with a Soft Serve instance using standard SSH commands to browse repositories, view directory trees, or print file contents.

• TUI: Jump directly into the interactive TUI.
• Directory Tree: Print a directory tree for a specific repository.
• Blob/File: Print a specific file. Use -c for syntax highlighting and -l for line numbers.

# Jump directly to a repo in the TUI
ssh git.charm.sh -t soft-serve

# Print out a directory tree for a repo
ssh git.charm.sh repo tree soft-serve

# Print a specific file
ssh git.charm.sh repo blob soft-serve cmd/soft/main.go

# Print a file with syntax highlighting and line numbers
ssh git.charm.sh repo blob soft-serve cmd/soft/main.go -c -l

To start a Soft Serve server, ensure git is installed and run the command soft serve.

By default, a data directory is created to store repositories, SSH keys, and the database.

Initial Admin Setup

When running the server for the first time, you must set the SOFT_SERVE_INITIAL_ADMIN_KEYS environment variable to your SSH authorized public key. This creates an admin user with full privileges.

Customizing Data and Config Paths

• To change the default data path, use the SOFT_SERVE_DATA_PATH environment variable.
• To override the program configuration location, use SOFT_SERVE_CONFIG_LOCATION (the file must be pre-created).

Soft Serve supports SQLite (default) and Postgres. Configuration can be done via config.yaml or environment variables.

Using Postgres

1. Create a database in Postgres: psql -h<hostname> -p<port> -U<user> -c 'CREATE DATABASE soft_serve'
2. Set the db.driver to postgres and provide the db.data_source connection string.

You can include a password directly in the connection string: postgres://myuser:dbpass@localhost:5432/my_soft_serve_db.

# config.yaml example for Postgres
db:
  driver: "postgres"
  data_source: "postgres://postgres@localhost:5432/soft_serve?sslmode=disable"

# Using environment variables for Postgres
SOFT_SERVE_DB_DRIVER=postgres \
SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres@localhost:5432/soft_serve?sslmode=disable" \
soft serve