Soft Serve

A tasty, self-hostable Git server for the command line. 🍦

Easy to navigate TUI available over SSH
Clone repos over SSH, HTTP, or Git protocol
Git LFS support with both HTTP and SSH backends
Manage repos with SSH
Create repos on demand with SSH or git push
Browse repos, files and commits with SSH-accessible UI
Print files over SSH with or without syntax highlighting and line numbers
Easy access control
- SSH authentication using public keys
- Allow/disallow anonymous access
- Add collaborators with SSH public keys
- Repos can be public or private
- User access tokens

Where can I see it?

Just run ssh git.charm.sh for an example. You can also try some of the following commands:

# 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

Or you can use Soft Serve to browse local repositories using soft browse [directory] or running soft within a Git repository.

Installation

Soft Serve is a single binary called soft. You can get it from a package manager:

# macOS or Linux
brew install charmbracelet/tap/soft-serve

# Windows (with Winget)
winget install charmbracelet.soft-serve

# Arch Linux
pacman -S soft-serve

# Nix
nix-env -iA nixpkgs.soft-serve

# Debian/Ubuntu
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install soft-serve

# Fedora/RHEL
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install soft-serve

You can also download a binary from the releases page. Packages are available in Alpine, Debian, and RPM formats. Binaries are available for Linux, macOS, and Windows.

Or just install it with go:

go install github.com/charmbracelet/soft-serve/cmd/soft@latest

A Docker image is also available.

Setting up a server

Make sure git is installed, then run soft serve. That’s it.

This will create a data directory that will store all the repos, ssh keys, and database.

By default, program configuration is stored within the data directory. But, this can be overridden by setting a custom path to a config file with SOFT_SERVE_CONFIG_LOCATION that is pre-created. If a config file pointed to by SOFT_SERVE_CONFIG_LOCATION, the default location within the data dir is used for generating a default config.

To change the default data path use SOFT_SERVE_DATA_PATH environment variable.

SOFT_SERVE_DATA_PATH=/var/lib/soft-serve soft serve

When you run Soft Serve for the first time, make sure you have the SOFT_SERVE_INITIAL_ADMIN_KEYS environment variable is set to your ssh authorized key. Any added key to this variable will be treated as admin with full privileges.

Using this environment variable, Soft Serve will create a new admin user that has full privileges. You can rename and change the user settings later.

Check out Systemd on how to run Soft Serve as a service using Systemd. Soft Serve packages in our Apt/Yum repositories come with Systemd service units.

Server Configuration

Once you start the server for the first time, the settings will be in config.yaml under your data directory. The default config.yaml is self-explanatory and will look like this:

# Soft Serve Server configurations

# The name of the server.
# This is the name that will be displayed in the UI.
name: "Soft Serve"

# Log format to use. Valid values are "json", "logfmt", and "text".
log_format: "text"

# The SSH server configuration.
ssh:
  # The address on which the SSH server will listen.
  listen_addr: ":23231"

  # The public URL of the SSH server.
  # This is the address that will be used to clone repositories.
  public_url: "ssh://localhost:23231"

  # The path to the SSH server's private key.
  key_path: "ssh/soft_serve_host"

  # The path to the SSH server's client private key.
  # This key will be used to authenticate the server to make git requests to
  # ssh remotes.
  client_key_path: "ssh/soft_serve_client"

  # The maximum number of seconds a connection can take.
  # A value of 0 means no timeout.
  max_timeout: 0

  # The number of seconds a connection can be idle before it is closed.
  idle_timeout: 120

# The Git daemon configuration.
git:
  # The address on which the Git daemon will listen.
  listen_addr: ":9418"

  # The maximum number of seconds a connection can take.
  # A value of 0 means no timeout.
  max_timeout: 0

  # The number of seconds a connection can be idle before it is closed.
  idle_timeout: 3

  # The maximum number of concurrent connections.
  max_connections: 32

# The HTTP server configuration.
http:
  # The address on which the HTTP server will listen.
  listen_addr: ":23232"

  # The path to the TLS private key.
  tls_key_path: ""

  # The path to the TLS certificate.
  tls_cert_path: ""

  # The public URL of the HTTP server.
  # This is the address that will be used to clone repositories.
  # Make sure to use https:// if you are using TLS.
  public_url: "http://localhost:23232"

  # The cross-origin request security options
  cors:
    # The allowed cross-origin headers
    allowed_headers:
      - "Accept"
      - "Accept-Language"
      - "Content-Language"
      - "Content-Type"
      - "Origin"
      - "X-Requested-With"
      - "User-Agent"
      - "Authorization"
      - "Access-Control-Request-Method"
      - "Access-Control-Allow-Origin"

    # The allowed cross-origin URLs
    allowed_origins:
      - "http://localhost:23232" # always allowed
      # - "https://example.com"

    # The allowed cross-origin methods
    allowed_methods:
      - "GET"
      - "HEAD"
      - "POST"
      - "PUT"
      - "OPTIONS"

# The database configuration.
db:
  # The database driver to use.
  # Valid values are "sqlite" and "postgres".
  driver: "sqlite"
  # The database data source name.
  # This is driver specific and can be a file path or connection string.
  # Make sure foreign key support is enabled when using SQLite.
  data_source: "soft-serve.db?_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)"

# Git LFS configuration.
lfs:
  # Enable Git LFS.
  enabled: true
  # Enable Git SSH transfer.
  ssh_enabled: false

# Cron job configuration
jobs:
  mirror_pull: "@every 10m"

# The stats server configuration.
stats:
  # The address on which the stats server will listen.
  listen_addr: ":23233"
# Additional admin keys.
#initial_admin_keys:
#  - "ssh-rsa AAAAB3NzaC1yc2..."

You can also use environment variables, to override these settings. All server settings environment variables start with SOFT_SERVE_ followed by the setting name all in uppercase. Here are some examples:

SOFT_SERVE_NAME: The name of the server that will appear in the TUI
SOFT_SERVE_SSH_LISTEN_ADDR: SSH listen address
SOFT_SERVE_SSH_KEY_PATH: SSH host key-pair path
SOFT_SERVE_HTTP_LISTEN_ADDR: HTTP listen address
SOFT_SERVE_HTTP_PUBLIC_URL: HTTP public URL used for cloning
SOFT_SERVE_GIT_MAX_CONNECTIONS: The number of simultaneous connections to git daemon

Database Configuration

Soft Serve supports both SQLite and Postgres for its database. Like all other Soft Serve settings, you can change the database driver and data source using either config.yaml or environment variables. The default config uses SQLite as the default database driver.

To use Postgres as your database, first create a Soft Serve database:

psql -h<hostname> -p<port> -U<user> -c 'CREATE DATABASE soft_serve'

Then set the database data source to point to your Postgres database. For instance, if you're running Postgres locally, using the default user postgres and using a database name soft_serve, you would have this config in your config file or environment variable:

db:
  driver: "postgres"
  data_source: "postgres://postgres@localhost:5432/soft_serv

Soft Serve

Install / Use

README

Soft Serve

Where can I see it?

Installation

Setting up a server

Server Configuration

Database Configuration