1# Soft Serve23<p>4 <img style="width: 451px" src="https://stuff.charm.sh/soft-serve/soft-serve-header.png?0" alt="A nice rendering of some melting ice cream with the words ‘Charm Soft Serve’ next to it"><br>5 <a href="https://github.com/charmbracelet/soft-serve/releases"><img src="https://img.shields.io/github/release/charmbracelet/soft-serve.svg" alt="Latest Release"></a>6 <a href="https://pkg.go.dev/github.com/charmbracelet/soft-serve?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>7 <a href="https://github.com/charmbracelet/soft-serve/actions"><img src="https://github.com/charmbracelet/soft-serve/workflows/build/badge.svg" alt="Build Status"></a>8 <a href="https://nightly.link/charmbracelet/soft-serve/workflows/nightly/main"><img src="https://shields.io/badge/-Nightly%20Builds-orange?logo=hackthebox&logoColor=fff&style=appveyor"/></a>9</p>1011A tasty, self-hostable Git server for the command line. 🍦1213<picture>14 <source media="(max-width: 750px)" srcset="https://github.com/charmbracelet/soft-serve/assets/42545625/c754c746-dc4c-44a6-9c39-28649264cbf2">15 <source media="(min-width: 750px)" width="750" srcset="https://github.com/charmbracelet/soft-serve/assets/42545625/c754c746-dc4c-44a6-9c39-28649264cbf2">16 <img src="https://github.com/charmbracelet/soft-serve/assets/42545625/c754c746-dc4c-44a6-9c39-28649264cbf2" alt="Soft Serve screencast">17</picture>1819- Easy to navigate TUI available over SSH20- Clone repos over SSH, HTTP, or Git protocol21- Git LFS support with both HTTP and SSH backends22- Manage repos with SSH23- Create repos on demand with SSH or `git push`24- Browse repos, files and commits with SSH-accessible UI25- Print files over SSH with or without syntax highlighting and line numbers26- Easy access control27 - SSH authentication using public keys28 - Allow/disallow anonymous access29 - Add collaborators with SSH public keys30 - Repos can be public or private31 - User access tokens3233## Where can I see it?3435Just run `ssh git.charm.sh` for an example. You can also try some of the following commands:3637```bash38# Jump directly to a repo in the TUI39ssh git.charm.sh -t soft-serve4041# Print out a directory tree for a repo42ssh git.charm.sh repo tree soft-serve4344# Print a specific file45ssh git.charm.sh repo blob soft-serve cmd/soft/main.go4647# Print a file with syntax highlighting and line numbers48ssh git.charm.sh repo blob soft-serve cmd/soft/main.go -c -l49```5051Or you can use Soft Serve to browse local repositories using `soft browse52[directory]` or running `soft` within a Git repository.5354## Installation5556Soft Serve is a single binary called `soft`. You can get it from a package57manager:5859```bash60# macOS or Linux61brew install charmbracelet/tap/soft-serve6263# Windows (with Winget)64winget install charmbracelet.soft-serve6566# Arch Linux67pacman -S soft-serve6869# Nix70nix-env -iA nixpkgs.soft-serve7172# Debian/Ubuntu73sudo mkdir -p /etc/apt/keyrings74curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg75echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list76sudo apt update && sudo apt install soft-serve7778# Fedora/RHEL79echo '[charm]80name=Charm81baseurl=https://repo.charm.sh/yum/82enabled=183gpgcheck=184gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo85sudo yum install soft-serve86```8788You can also download a binary from the [releases][releases] page. Packages are89available in Alpine, Debian, and RPM formats. Binaries are available for Linux,90macOS, and Windows.9192[releases]: https://github.com/charmbracelet/soft-serve/releases9394Or just install it with `go`:9596```bash97go install github.com/charmbracelet/soft-serve/cmd/soft@latest98```99100A [Docker image][docker] is also available.101102[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md103104## Setting up a server105106Make sure `git` is installed, then run `soft serve`. That’s it.107108This will create a `data` directory that will store all the repos, ssh keys,109and database.110111By default, program configuration is stored within the `data` directory. But,112this can be overridden by setting a custom path to a config file with `SOFT_SERVE_CONFIG_LOCATION`113that is pre-created. If a config file pointed to by `SOFT_SERVE_CONFIG_LOCATION`,114the default location within the `data` dir is used for generating a default config.115116To change the default data path use `SOFT_SERVE_DATA_PATH` environment variable.117118```sh119SOFT_SERVE_DATA_PATH=/var/lib/soft-serve soft serve120```121122When you run Soft Serve for the first time, make sure you have the123`SOFT_SERVE_INITIAL_ADMIN_KEYS` environment variable is set to your ssh124authorized key. Any added key to this variable will be treated as admin with125full privileges.126127Using this environment variable, Soft Serve will create a new `admin` user that128has full privileges. You can rename and change the user settings later.129130Check out [Systemd][systemd] on how to run Soft Serve as a service using131Systemd. Soft Serve packages in our Apt/Yum repositories come with Systemd132service units.133134[systemd]: https://github.com/charmbracelet/soft-serve/blob/main/systemd.md135136### Server Configuration137138Once you start the server for the first time, the settings will be in139`config.yaml` under your data directory. The default `config.yaml` is140self-explanatory and will look like this:141142```yaml143# Soft Serve Server configurations144145# The name of the server.146# This is the name that will be displayed in the UI.147name: "Soft Serve"148149# Log format to use. Valid values are "json", "logfmt", and "text".150log_format: "text"151152# The SSH server configuration.153ssh:154 # The address on which the SSH server will listen.155 listen_addr: ":23231"156157 # The public URL of the SSH server.158 # This is the address that will be used to clone repositories.159 public_url: "ssh://localhost:23231"160161 # The path to the SSH server's private key.162 key_path: "ssh/soft_serve_host"163164 # The path to the SSH server's client private key.165 # This key will be used to authenticate the server to make git requests to166 # ssh remotes.167 client_key_path: "ssh/soft_serve_client"168169 # The maximum number of seconds a connection can take.170 # A value of 0 means no timeout.171 max_timeout: 0172173 # The number of seconds a connection can be idle before it is closed.174 idle_timeout: 120175176# The Git daemon configuration.177git:178 # The address on which the Git daemon will listen.179 listen_addr: ":9418"180181 # The maximum number of seconds a connection can take.182 # A value of 0 means no timeout.183 max_timeout: 0184185 # The number of seconds a connection can be idle before it is closed.186 idle_timeout: 3187188 # The maximum number of concurrent connections.189 max_connections: 32190191# The HTTP server configuration.192http:193 # The address on which the HTTP server will listen.194 listen_addr: ":23232"195196 # The path to the TLS private key.197 tls_key_path: ""198199 # The path to the TLS certificate.200 tls_cert_path: ""201202 # The public URL of the HTTP server.203 # This is the address that will be used to clone repositories.204 # Make sure to use https:// if you are using TLS.205 public_url: "http://localhost:23232"206207# The database configuration.208db:209 # The database driver to use.210 # Valid values are "sqlite" and "postgres".211 driver: "sqlite"212 # The database data source name.213 # This is driver specific and can be a file path or connection string.214 # Make sure foreign key support is enabled when using SQLite.215 data_source: "soft-serve.db?_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)"216217# Git LFS configuration.218lfs:219 # Enable Git LFS.220 enabled: true221 # Enable Git SSH transfer.222 ssh_enabled: false223224# Cron job configuration225jobs:226 mirror_pull: "@every 10m"227228# The stats server configuration.229stats:230 # The address on which the stats server will listen.231 listen_addr: ":23233"232# Additional admin keys.233#initial_admin_keys:234# - "ssh-rsa AAAAB3NzaC1yc2..."235```236237You can also use environment variables, to override these settings. All server238settings environment variables start with `SOFT_SERVE_` followed by the setting239name all in uppercase. Here are some examples:240241- `SOFT_SERVE_NAME`: The name of the server that will appear in the TUI242- `SOFT_SERVE_SSH_LISTEN_ADDR`: SSH listen address243- `SOFT_SERVE_SSH_KEY_PATH`: SSH host key-pair path244- `SOFT_SERVE_HTTP_LISTEN_ADDR`: HTTP listen address245- `SOFT_SERVE_HTTP_PUBLIC_URL`: HTTP public URL used for cloning246- `SOFT_SERVE_GIT_MAX_CONNECTIONS`: The number of simultaneous connections to git daemon247248#### Database Configuration249250Soft 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.251252To use Postgres as your database, first create a Soft Serve database:253254```sh255psql -h<hostname> -p<port> -U<user> -c 'CREATE DATABASE soft_serve'256```257258Then 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:259260```261db:262 driver: "postgres"263 data_source: "postgres://postgres@localhost:5432/soft_serve?sslmode=disable"264```265266Environment variables equivalent:267268```sh269SOFT_SERVE_DB_DRIVER=postgres \270SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres@localhost:5432/soft_serve?sslmode=disable" \271soft serve272```273274You can specify a database connection password in the _data source_ url. For example, `postgres://myuser:dbpass@localhost:5432/my_soft_serve_db`.275276#### LFS Configuration277278Soft Serve supports both Git LFS [HTTP](https://github.com/git-lfs/git-lfs/blob/main/docs/api/README.md) and [SSH](https://github.com/git-lfs/git-lfs/blob/main/docs/proposals/ssh_adapter.md) protocols out of the box, there is no need to do any extra set up.279280Use the `lfs` config section to customize your Git LFS server.281282> **Note**: The pure-SSH transfer is disabled by default.283284## Server Access285286Soft Serve at its core manages your server authentication and authorization. Authentication verifies the identity of a user, while authorization determines their access rights to a repository.287288To manage the server users, access, and repos, you can use the SSH command line interface.289290Try `ssh localhost -i ~/.ssh/id_ed25519 -p 23231 help` for more info. Make sure291you use your key here.292293For ease of use, instead of specifying the key, port, and hostname every time294you SSH into Soft Serve, add your own Soft Serve instance entry to your SSH295config. For instance, to use `ssh soft` instead of typing `ssh localhost -i296~/.ssh/id_ed25519 -p 23231`, we can define a `soft` entry in our SSH config297file `~/.ssh/config`.298299```conf300Host soft301 HostName localhost302 Port 23231303 IdentityFile ~/.ssh/id_ed25519304```305306Now, we can do `ssh soft` to SSH into Soft Serve. Since `git` is also aware of307this config, you can use `soft` as the hostname for your clone commands.308309```sh310git clone ssh://soft/dotfiles311# make changes312# add & commit313git push origin main314```315316> **Note** The `-i` part will be omitted in the examples below for brevity. You317> can add your server settings to your sshconfig for quicker access.318319### Authentication320321Everything that needs authentication is done using SSH. Make sure you have322added an entry for your Soft Serve instance in your `~/.ssh/config` file.323324By default, Soft Serve gives read-only permission to anonymous connections to325any of the above protocols. This is controlled by two settings `anon-access`326and `allow-keyless`.327328- `anon-access`: Defines the access level for anonymous users. Available329 options are `no-access`, `read-only`, `read-write`, and `admin-access`.330 Default is `read-only`.331- `allow-keyless`: Whether to allow connections that doesn't use keys to pass.332 Setting this to `false` would disable access to SSH keyboard-interactive,333 HTTP, and Git protocol connections. Default is `true`.334335```sh336$ ssh -p 23231 localhost settings337Manage server settings338339Usage:340 ssh -p 23231 localhost settings [command]341342Available Commands:343 allow-keyless Set or get allow keyless access to repositories344 anon-access Set or get the default access level for anonymous users345346Flags:347 -h, --help help for settings348349Use "ssh -p 23231 localhost settings [command] --help" for more information about a command.350```351352> **Note** These settings can only be changed by admins.353354When `allow-keyless` is disabled, connections that don't use SSH Public Key355authentication will get denied. This means cloning repos over HTTP(s) or git://356will get denied.357358Meanwhile, `anon-access` controls the access level granted to connections that359use SSH Public Key authentication but are not registered users. The default360setting for this is `read-only`. This will grant anonymous connections that use361SSH Public Key authentication `read-only` access to public repos.362363`anon-access` is also used in combination with `allow-keyless` to determine the364access level for HTTP(s) and git:// clone requests.365366#### SSH367368Soft Serve doesn't allow duplicate SSH public keys for users. A public key can be associated with one user only. This makes SSH authentication simple and straight forward, add your public key to your Soft Serve user to be able to access Soft Serve.369370#### HTTP371372You can generate user access tokens through the SSH command line interface. Access tokens can have an optional expiration date. Use your access token as the basic auth user to access your Soft Serve repos through HTTP.373374```sh375# Create a user token376ssh -p 23231 localhost token create 'my new token'377ss_1234abc56789012345678901234de246d798fghi378379# Or with an expiry date380ssh -p 23231 localhost token create --expires-in 1y 'my other token'381ss_98fghi1234abc56789012345678901234de246d7382```383384Now you can access to repos that require `read-write` access.385386```sh387git clone http://ss_98fghi1234abc56789012345678901234de246d7@localhost:23232/my-private-repo.git my-private-repo388# Make changes and push389```390391### Authorization392393Soft Serve offers a simple access control. There are four access levels,394no-access, read-only, read-write, and admin-access.395396`admin-access` has full control of the server and can make changes to users and repos.397398`read-write` access gets full control of repos.399400`read-only` can read public repos.401402`no-access` denies access to all repos.403404## User Management405406Admins can manage users and their keys using the `user` command. Once a user is407created and has access to the server, they can manage their own keys and408settings.409410To create a new user simply use `user create`:411412```sh413# Create a new user414ssh -p 23231 localhost user create beatrice415416# Add user keys417ssh -p 23231 localhost user add-pubkey beatrice ssh-rsa AAAAB3Nz...418ssh -p 23231 localhost user add-pubkey beatrice ssh-ed25519 AAAA...419420# Create another user with public key421ssh -p 23231 localhost user create frankie '-k "ssh-ed25519 AAAATzN..."'422423# Need help?424ssh -p 23231 localhost user help425```426427Once a user is created, they get `read-only` access to public repositories.428They can also create new repositories on the server.429430Users can manage their keys using the `pubkey` command:431432```sh433# List user keys434ssh -p 23231 localhost pubkey list435436# Add key437ssh -p 23231 localhost pubkey add ssh-ed25519 AAAA...438439# Wanna change your username?440ssh -p 23231 localhost set-username yolo441442# To display user info443ssh -p 23231 localhost info444```445446## Repositories447448You can manage repositories using the `repo` command.449450```sh451# Run repo help452$ ssh -p 23231 localhost repo help453Manage repositories454455Usage:456 ssh -p 23231 localhost repo [command]457458Aliases:459 repo, repos, repository, repositories460461Available Commands:462 blob Print out the contents of file at path463 branch Manage repository branches464 collab Manage collaborators465 create Create a new repository466 delete Delete a repository467 description Set or get the description for a repository468 hide Hide or unhide a repository469 import Import a new repository from remote470 info Get information about a repository471 is-mirror Whether a repository is a mirror472 list List repositories473 private Set or get a repository private property474 project-name Set or get the project name for a repository475 rename Rename an existing repository476 tag Manage repository tags477 tree Print repository tree at path478479Flags:480 -h, --help help for repo481482Use "ssh -p 23231 localhost repo [command] --help" for more information about a command.483```484485To use any of the above `repo` commands, a user must be a collaborator in the repository. More on this below.486487### Creating Repositories488489To create a repository, first make sure you are a registered user. Use the490`repo create <repo>` command to create a new repository:491492```sh493# Create a new repository494ssh -p 23231 localhost repo create icecream495496# Create a repo with description497ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"'498499# ... and project name500ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' '-n "Ice Cream"'501502# I need my repository private!503ssh -p 23231 localhost repo create icecream -p '-d "This is an Ice Cream description"' '-n "Ice Cream"'504505# Help?506ssh -p 23231 localhost repo create -h507```508509Or you can add your Soft Serve server as a remote to any existing repo, given510you have write access, and push to remote:511512```513git remote add origin ssh://localhost:23231/icecream514```515516After you’ve added the remote just go ahead and push. If the repo doesn’t exist517on the server it’ll be created.518519```520git push origin main521```522523### Nested Repositories524525Repositories can be nested too:526527```sh528# Create a new nested repository529ssh -p 23231 localhost repo create charmbracelet/icecream530531# Or ...532git remote add charm ssh://localhost:23231/charmbracelet/icecream533git push charm main534```535536### Mirrors537538You can also *import* repositories from any public remote. Use the `repo import` command.539540```sh541ssh -p 23231 localhost repo import soft-serve https://github.com/charmbracelet/soft-serve542```543544Use `--mirror` or `-m` to mark the repository as a *pull* mirror.545546### Deleting Repositories547548You can delete repositories using the `repo delete <repo>` command.549550```sh551ssh -p 23231 localhost repo delete icecream552```553554### Renaming Repositories555556Use the `repo rename <old> <new>` command to rename existing repositories.557558```sh559ssh -p 23231 localhost repo rename icecream vanilla560```561562### Repository Collaborators563564Sometimes you want to restrict write access to certain repositories. This can565be achieved by adding a collaborator to your repository.566567Use the `repo collab <command> <repo>` command to manage repo collaborators.568569```sh570# Add collaborator to soft-serve571ssh -p 23231 localhost repo collab add soft-serve frankie572573# Add collaborator with a specific access level574ssh -p 23231 localhost repo collab add soft-serve beatrice read-only575576# Remove collaborator577ssh -p 23231 localhost repo collab remove soft-serve beatrice578579# List collaborators580ssh -p 23231 localhost repo collab list soft-serve581```582583### Repository Metadata584585You can also change the repo's description, project name, whether it's private,586etc using the `repo <command>` command.587588```sh589# Set description for repo590ssh -p 23231 localhost repo description icecream "This is a new description"591592# Hide repo from listing593ssh -p 23231 localhost repo hidden icecream true594595# List repository info (branches, tags, description, etc)596ssh -p 23231 localhost repo icecream info597```598599To make a repository private, use `repo private <repo> [true|false]`. Private600repos can only be accessed by admins and collaborators.601602```sh603ssh -p 23231 localhost repo private icecream true604```605606### Repository Branches & Tags607608Use `repo branch` and `repo tag` to list, and delete branches or tags. You can609also use `repo branch default` to set or get the repository default branch.610611### Repository Tree612613To print a file tree for the project, just use the `repo tree` command along with614the repo name as the SSH command to your Soft Serve server:615616```sh617ssh -p 23231 localhost repo tree soft-serve618```619620You can also specify the sub-path and a specific reference or branch.621622```sh623ssh -p 23231 localhost repo tree soft-serve server/config624ssh -p 23231 localhost repo tree soft-serve main server/config625```626627From there, you can print individual files using the `repo blob` command:628629```sh630ssh -p 23231 localhost repo blob soft-serve cmd/soft/main.go631```632633You can add the `-c` flag to enable syntax coloring and `-l` to print line634numbers:635636```sh637ssh -p 23231 localhost repo blob soft-serve cmd/soft/main.go -c -l638639```640641Use `--raw` to print raw file contents. This is useful for dumping binary data.642643### Repository webhooks644645Soft Serve supports repository webhooks using the `repo webhook` command. You646can create and manage webhooks for different repository events such as _push_,647_collaborators_, and _branch_tag_create_ events.648649```650Manage repository webhooks651652Usage:653 ssh -p 23231 localhost repo webhook [command]654655Aliases:656 webhook, webhooks657658Available Commands:659 create Create a repository webhook660 delete Delete a repository webhook661 deliveries Manage webhook deliveries662 list List repository webhooks663 update Update a repository webhook664665Flags:666 -h, --help help for webhook667```668669## The Soft Serve TUI670671<img src="https://stuff.charm.sh/soft-serve/soft-serve-demo-commit.png" width="750" alt="TUI example showing a diff">672673Soft Serve TUI is mainly used to browse repos over SSH. You can also use it to674browse local repositories with `soft browse` or running `soft` within a Git675repository.676677```sh678ssh localhost -p 23231679```680681It's also possible to “link” to a specific repo:682683```sh684ssh -p 23231 localhost -t soft-serve685```686687You can copy text to your clipboard over SSH. For instance, you can press688<kbd>c</kbd> on the highlighted repo in the menu to copy the clone command689[^osc52].690691[^osc52]:692 Copying over SSH depends on your terminal support of OSC52. Refer to693 [go-osc52](https://github.com/aymanbagabas/go-osc52) for more information.694695## Hooks696697Soft Serve supports git server-side hooks `pre-receive`, `update`,698`post-update`, and `post-receive`. This means you can define your own hooks to699run on repository push events. Hooks can be defined as a per-repository hook,700and/or global hooks that run for all repositories.701702You can find per-repository hooks under the repository `hooks` directory.703704Globs hooks can be found in your `SOFT_SERVE_DATA_PATH` directory under705`hooks`. Defining global hooks is useful if you want to run CI/CD for example.706707Here's an example of sending a message after receiving a push event. Create an708executable file `<data path>/hooks/update`:709710```sh711#!/bin/sh712#713# An example hook script to echo information about the push714# and send it to the client.715716refname="$1"717oldrev="$2"718newrev="$3"719720# Safety check721if [ -z "$GIT_DIR" ]; then722 echo "Don't run this script from the command line." >&2723 echo " (if you want, you could supply GIT_DIR then run" >&2724 echo " $0 <ref> <oldrev> <newrev>)" >&2725 exit 1726fi727728if [ -z "$refname" -o -z "$oldrev" -o -z "$newrev" ]; then729 echo "usage: $0 <ref> <oldrev> <newrev>" >&2730 exit 1731fi732733# Check types734# if $newrev is 0000...0000, it's a commit to delete a ref.735zero=$(git hash-object --stdin </dev/null | tr '[0-9a-f]' '0')736if [ "$newrev" = "$zero" ]; then737 newrev_type=delete738else739 newrev_type=$(git cat-file -t $newrev)740fi741742echo "Hi from Soft Serve update hook!"743echo744echo "RefName: $refname"745echo "Change Type: $newrev_type"746echo "Old SHA1: $oldrev"747echo "New SHA1: $newrev"748749exit 0750```751752Now, you should get a message after pushing changes to any repository.753754## A note about RSA keys755756Unfortunately, due to a shortcoming in Go’s `x/crypto/ssh` package, Soft Serve757does not currently support access via new SSH RSA keys: only the old SHA-1758ones will work.759760Until we sort this out you’ll either need an SHA-1 RSA key or a key with761another algorithm, e.g. Ed25519. Not sure what type of keys you have?762You can check with the following:763764```sh765$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;766```767768If you’re curious about the inner workings of this problem have a look at:769770- https://github.com/golang/go/issues/37278771- https://go-review.googlesource.com/c/crypto/+/220037772- https://github.com/golang/crypto/pull/197773774## Contributing775776See [contributing][contribute].777778[contribute]: https://github.com/charmbracelet/soft-serve/contribute779780## Feedback781782We’d love to hear your thoughts on this project. Feel free to drop us a note!783784- [Twitter](https://twitter.com/charmcli)785- [The Fediverse](https://mastodon.social/@charmcli)786- [Discord](https://charm.sh/chat)787788## License789790[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)791792---793794Part of [Charm](https://charm.sh).795796<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>797798Charm热爱开源 • Charm loves open source