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://pkg.go.dev/github.com/charmbracelet/soft-serve?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
 11    <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>
 12    <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>
 13</p>
 14
 15A tasty, self-hostable Git server for the command line. 🍦
 16
 17<img src="https://stuff.charm.sh/soft-serve/soft-serve-cli-demo.gif" width="700" alt="Soft Serve screencast">
 18
 19* Configure with `git`
 20* Create repos on demand with `git push`
 21* Browse repos with an SSH-accessible TUI
 22* Easy access control
 23  - Allow/disallow anonymous access
 24  - Add collaborators with SSH public keys
 25  - Repos can be public or private
 26
 27## Where can I see it?
 28
 29Just run `ssh git.charm.sh` for an example.
 30
 31## Installation
 32
 33Soft Serve is a single binary called `soft`. You can get it from a package
 34manager:
 35
 36```bash
 37# macOS or Linux
 38brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
 39
 40# Arch Linux
 41yay -S soft-serve
 42```
 43
 44You can also download a binary from the [releases][releases] page. Packages are
 45available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
 46macOS, and Windows.
 47
 48[releases]: https://github.com/charmbracelet/soft-serve/releases
 49
 50Or just install it with `go`:
 51
 52```bash
 53go install github.com/charmbracelet/soft-serve/cmd/soft@latest
 54```
 55
 56## Setting up a server
 57
 58Make sure `git` is installed, then run `soft`. That’s it.
 59
 60A [Docker image][docker] is also available.
 61
 62[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
 63
 64## Configuration
 65
 66The Soft Serve configuration is simple and straightforward:
 67
 68```yaml
 69# The name of the server to show in the TUI.
 70name: Soft Serve
 71
 72# The host and port to display in the TUI. You may want to change this if your
 73# server is accessible from a different host and/or port that what it's
 74# actually listening on (for example, if it's behind a reverse proxy).
 75host: localhost
 76port: 23231
 77
 78# The access level for anonymous users. Options are: read-write, read-only
 79# and no-access.
 80anon-access: read-write
 81
 82# You can grant read-only access to users without private keys.
 83allow-keyless: false
 84
 85# Which repos should appear in the menu?
 86repos:
 87  - name: Home
 88    repo: config
 89    private: true
 90    note: "Configuration and content repo for this server"
 91  - name: Example Public Repo
 92    repo: my-public-repo
 93    private: false
 94    note: "A publicly-accessible repo"
 95  - name: Example Private Repo
 96    repo: my-private-repo
 97    private: true
 98    note: "A private repo"
 99
100# Authorized users. Admins have full access to all repos. Regular users
101# can read all repos and push to their collab-repos.
102users:
103  - name: Beatrice
104    admin: true
105    public-keys:
106      - ssh-rsa AAAAB3Nz...   # redacted
107      - ssh-ed25519 AAAA...   # redacted
108  - name: Frankie
109    collab-repos:
110      - my-public-repo
111      - my-private-repo
112    public-keys:
113      - ssh-rsa AAAAB3Nz...   # redacted
114      - ssh-ed25519 AAAA...   # redacted
115```
116
117When `soft` is run for the first time, it creates a configuration repo
118containing the main README displayed in the TUI as well as a config file for
119user access control.
120
121```
122git clone ssh://localhost:23231/config
123```
124
125The `config` repo is publicly writable by default, so be sure to setup your
126access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
127environment variable before first run and it will restrict access to that
128initial public key until you configure things otherwise.
129If you're having trouble, make sure you have generated keys with `ssh-keygen`
130as configuration is not supported for keyless users.
131
132## Pushing (and creating!) repos
133
134You can add your Soft Serve server as a remote to any existing repo:
135
136```
137git remote add soft ssh://localhost:23231/REPO
138```
139
140After you’ve added the remote just go ahead and push. If the repo doesn’t exist
141on the server it’ll be created.
142
143```
144git push soft main
145```
146
147## The Soft Serve TUI
148
149Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
150grabbing clone commands:
151
152```
153ssh localhost -p 23231
154```
155
156It's also possible to “link” to a specific repo:
157
158```
159ssh localhost -t -p 23231 REPO
160```
161
162### Server Settings
163
164In addition to the Git-based configuration above, there are a few
165environment-level settings:
166
167* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
168* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
169* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
170* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
171* `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.
172
173
174### A note about RSA keys
175
176Unfortunately, due to a shortcoming in Go’s `x/crypto/ssh` package, Soft Serve
177does not currently support access via new SSH RSA keys: only the old SHA-1
178ones will work.
179
180Until we sort this out you'll either need an SHA-1 RSA key or a key with
181another algorithm, e.g. Ed25519. Not sure what type of keys you have?
182You can check with the following:
183
184```
185$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;
186```
187
188If you're curious about the inner workings of this problem have a look at:
189
190- https://github.com/golang/go/issues/37278
191- https://go-review.googlesource.com/c/crypto/+/220037
192- https://github.com/golang/crypto/pull/197
193
194## License
195
196[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
197
198***
199
200Part of [Charm](https://charm.sh).
201
202<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
203
204Charm热爱开源 • Charm loves open source