1Soft Serve
  2==========
  3
  4<p>
  5    <picture>
  6        <source srcset="https://stuff.charm.sh/soft-serve/soft-serve-header.webp?0" type="image/webp">
  7        <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">
  8    </picture><br>
  9    <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>
 10    <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>
 11</p>
 12
 13A tasty, self-hostable Git server for the command line. 🍦
 14
 15<img src="https://stuff.charm.sh/soft-serve/soft-serve-cli-demo.gif" width="700" alt="Soft Serve screencast">
 16
 17* Configure with `git`
 18* Create repos on demand with `git push`
 19* Browse repos with an SSH-accessible TUI
 20* Easy access control
 21  - Allow/disallow anonymous access
 22  - Add collaborators with SSH public keys
 23  - Repos can be public or private
 24
 25## Where can I see it?
 26
 27Just run `ssh git.charm.sh` for an example.
 28
 29## Installation
 30
 31Soft Serve is a single binary called `soft`. You can get it from a package
 32manager:
 33
 34```bash
 35# macOS or Linux
 36brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
 37
 38# Arch Linux
 39yay -S soft-serve
 40```
 41
 42You can also download a binary from the [releases][releases] page. Packages are
 43available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
 44macOS, and Windows.
 45
 46[releases]: https://github.com/charmbracelet/soft-serve/releases
 47
 48Or just install it with `go`:
 49
 50```bash
 51go install github.com/charmbracelet/soft-serve/cmd/soft@latest
 52```
 53
 54## Setting up a server
 55
 56Make sure `git` is installed, then run `soft`. That’s it.
 57
 58A [Docker image][docker] is also available.
 59
 60[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
 61
 62## Configuration
 63
 64The Soft Serve configuration is simple and straightforward:
 65
 66```yaml
 67# The name of the server to show in the TUI.
 68name: Soft Serve
 69
 70# The host and port to display in the TUI. You may want to change this if your
 71# server is accessible from a different host and/or port that what it's
 72# actually listening on (for example, if it's behind a reverse proxy).
 73host: localhost
 74port: 23231
 75
 76# The access level for anonymous users. Options are: read-write, read-only
 77# and no-access.
 78anon-access: read-write
 79
 80# You can grant read-only access to users without private keys.
 81allow-keyless: false
 82
 83# Which repos should appear in the menu?
 84repos:
 85  - name: Home
 86    repo: config
 87    private: true
 88    note: "Configuration and content repo for this server"
 89  - name: Example Public Repo
 90    repo: my-public-repo
 91    private: false
 92    note: "A publicly-accessible repo"
 93  - name: Example Private Repo
 94    repo: my-private-repo
 95    private: true
 96    note: "A private repo"
 97
 98# Authorized users. Admins have full access to all repos. Regular users
 99# can read all repos and push to their collab-repos.
100users:
101  - name: Beatrice
102    admin: true
103    public-keys:
104      - KEY TEXT
105  - name: Frankie
106    collab-repos:
107      - my-public-repo
108      - my-private-repo
109    public-keys:
110      - KEY TEXT
111```
112
113When `soft` is run for the first time, it creates a configuration repo
114containing the main README displayed in the TUI as well as a config file for
115user access control.
116
117```
118git clone ssh://localhost:23231/config
119```
120
121The `config` repo is publicly writable by default, so be sure to setup your
122access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
123environment variable before first run and it will restrict access to that
124initial public key until you configure things otherwise.
125
126## Pushing (and creating!) repos
127
128You can add your Soft Serve server as a remote to any existing repo:
129
130```
131git remote add soft ssh://localhost:23231/REPO
132```
133
134After you’ve added the remote just go ahead and push. If the repo doesn’t exist
135on the server it’ll be created.
136
137```
138git push soft main
139```
140
141## The Soft Serve TUI
142
143Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
144grabbing clone commands:
145
146```
147ssh localhost -p 23231
148```
149
150It's also possible to “link” to a specific repo:
151
152```
153ssh localhost -t -p 23231 REPO
154```
155
156### Server Settings
157
158In addition to the Git-based configuration above, there are a few
159environment-level settings:
160
161* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
162* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
163* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
164* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
165* `SOFT_SERVE_INITIAL_ADMIN_KEY`: The public key that will initially have admin access to repos (_default ""_). This must be set before `soft` runs for the first time and creates the `config` repo. If set after the `config` repo has been created, this setting has no effect.
166
167## License
168
169[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
170
171***
172
173Part of [Charm](https://charm.sh).
174
175<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
176
177Charm热爱开源 • Charm loves open source