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?0" width="750" alt="Soft Serve screencast">
 18
 19* Configure with `git`
 20* Create repos on demand with `git push`
 21* Browse repos, files and commits with an SSH-accessible TUI
 22* Print files over SSH with or without syntax highlighting and line numbers
 23* Easy access control
 24  - Allow/disallow anonymous access
 25  - Add collaborators with SSH public keys
 26  - Repos can be public or private
 27
 28## Where can I see it?
 29
 30Just run `ssh git.charm.sh` for an example. You can also try some of the following commands:
 31
 32```bash
 33# Jump directly to a repo in the TUI
 34ssh git.charm.sh -t soft-serve
 35
 36# Print out a directory tree for a repo
 37ssh git.charm.sh soft-serve
 38
 39# Print a specific file
 40ssh git.charm.sh soft-serve/cmd/soft/main.go
 41
 42# Print a file with syntax highlighting and line numbers
 43ssh git.charm.sh soft-serve/cmd/soft/main.go -c -l
 44```
 45
 46## Installation
 47
 48Soft Serve is a single binary called `soft`. You can get it from a package
 49manager:
 50
 51```bash
 52# macOS or Linux
 53brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
 54
 55# Arch Linux
 56pacman -S soft-serve
 57```
 58
 59You can also download a binary from the [releases][releases] page. Packages are
 60available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
 61macOS, and Windows.
 62
 63[releases]: https://github.com/charmbracelet/soft-serve/releases
 64
 65Or just install it with `go`:
 66
 67```bash
 68go install github.com/charmbracelet/soft-serve/cmd/soft@latest
 69```
 70
 71## Setting up a server
 72
 73Make sure `git` is installed, then run `soft`. That’s it.
 74
 75A [Docker image][docker] is also available.
 76
 77[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
 78
 79## Configuration
 80
 81The Soft Serve configuration is simple and straightforward:
 82
 83```yaml
 84# The name of the server to show in the TUI.
 85name: Soft Serve
 86
 87# The host and port to display in the TUI. You may want to change this if your
 88# server is accessible from a different host and/or port that what it's
 89# actually listening on (for example, if it's behind a reverse proxy).
 90host: localhost
 91port: 23231
 92
 93# The access level for anonymous users. Options are: read-write, read-only
 94# and no-access.
 95anon-access: read-write
 96
 97# You can grant read-only access to users without private keys.
 98allow-keyless: false
 99
100# Customize repos in the menu
101repos:
102  - name: Home
103    repo: config
104    private: true
105    note: "Configuration and content repo for this server"
106  - name: Example Public Repo
107    repo: my-public-repo
108    private: false
109    note: "A publicly-accessible repo"
110    readme: docs/README.md
111  - name: Example Private Repo
112    repo: my-private-repo
113    private: true
114    note: "A private repo"
115
116# Authorized users. Admins have full access to all repos. Regular users
117# can read all repos and push to their collab-repos.
118users:
119  - name: Beatrice
120    admin: true
121    public-keys:
122      - ssh-rsa AAAAB3Nz...   # redacted
123      - ssh-ed25519 AAAA...   # redacted
124  - name: Frankie
125    collab-repos:
126      - my-public-repo
127      - my-private-repo
128    public-keys:
129      - ssh-rsa AAAAB3Nz...   # redacted
130      - ssh-ed25519 AAAA...   # redacted
131```
132
133When `soft` is run for the first time, it creates a configuration repo
134containing the main README displayed in the TUI as well as a config file for
135user access control.
136
137```
138git clone ssh://localhost:23231/config
139```
140
141The `config` repo is publicly writable by default, so be sure to setup your
142access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
143environment variable before first run and it will restrict access to that
144initial public key until you configure things otherwise.
145If you're having trouble, make sure you have generated keys with `ssh-keygen`
146as configuration is not supported for keyless users.
147
148### Server Settings
149
150In addition to the Git-based configuration above, there are a few
151environment-level settings:
152
153* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
154* `SOFT_SERVE_HOST`: Address to use in public clone URLs
155* `SOFT_SERVE_BIND_ADDRESS`: Network interface to listen on (_default 0.0.0.0_)
156* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
157* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
158* `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.
159
160## Pushing (and creating!) repos
161
162You can add your Soft Serve server as a remote to any existing repo:
163
164```
165git remote add soft ssh://localhost:23231/REPO
166```
167
168After you’ve added the remote just go ahead and push. If the repo doesn’t exist
169on the server it’ll be created.
170
171```
172git push soft main
173```
174
175## The Soft Serve TUI
176
177<img src="https://stuff.charm.sh/soft-serve/soft-serve-tui-diff.png" width="750" alt="TUI example showing a diff">
178
179Soft Serve serves a TUI over SSH for browsing repos, viewing files and commits,
180and grabbing clone commands:
181
182```
183ssh localhost -p 23231
184```
185
186It's also possible to “link” to a specific repo:
187
188```
189ssh localhost -t -p 23231 REPO
190```
191
192You can use the `tab` key to move between the repo menu and a particular repo.
193When a repo is highlighted you can use the following keys for navigation:
194
195* `R` – View the project's README file
196* `F` – Navigate and view all of the files in the project
197* `C` – View the commit log for the repo
198* `B` – View branches and tags for the repo
199
200## Printing files over SSH
201
202<img src="https://stuff.charm.sh/soft-serve/soft-serve-cat-example.png?1" width="750" alt="Example tree and file output on the CLI">
203
204Soft Serve also has the ability to print files and directories directly from a
205remote repo without the need to clone or use the TUI.
206
207To print a file tree for the project, just use the repo name as the SSH command
208to your Soft Serve server:
209
210```
211ssh git.charm.sh soft-serve
212```
213
214From there you can print individual files:
215
216```
217ssh git.charm.sh soft-serve/cmd/soft/main.go
218```
219
220You can add the `-c` flag to enable syntax coloring and `-l` to print line
221numbers:
222
223```
224ssh git.charm.sh soft-serve/cmd/soft/main.go -c -l
225```
226
227### A note about RSA keys
228
229Unfortunately, due to a shortcoming in Go’s `x/crypto/ssh` package, Soft Serve
230does not currently support access via new SSH RSA keys: only the old SHA-1
231ones will work.
232
233Until we sort this out you'll either need an SHA-1 RSA key or a key with
234another algorithm, e.g. Ed25519. Not sure what type of keys you have?
235You can check with the following:
236
237```
238$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;
239```
240
241If you’re curious about the inner workings of this problem have a look at:
242
243- https://github.com/golang/go/issues/37278
244- https://go-review.googlesource.com/c/crypto/+/220037
245- https://github.com/golang/crypto/pull/197
246
247## Feedback
248
249We’d love to hear your thoughts on this project. Feel free to drop us a note!
250
251* [Twitter](https://twitter.com/charmcli)
252* [The Fediverse](https://mastodon.technology/@charm)
253* [Slack](https://charm.sh/slack)
254
255## License
256
257[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
258
259***
260
261Part of [Charm](https://charm.sh).
262
263<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
264
265Charm热爱开源 • Charm loves open source