1Soft Serve
  2==========
  3
  4<p>
  5    <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>
  6    <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>
  7    <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>
  8    <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>
  9    <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>
 10</p>
 11
 12A tasty, self-hostable Git server for the command line. 🍦
 13
 14<picture>
 15  <source media="(max-width: 750px)" srcset="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0">
 16  <source media="(min-width: 750px)" width="750" srcset="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0">
 17  <img src="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0" alt="Soft Serve screencast">
 18</picture>
 19
 20* Configure with `git`
 21* Create repos on demand with `git push`
 22* Browse repos, files and commits with an SSH-accessible TUI
 23* TUI mouse support
 24* Print files over SSH with or without syntax highlighting and line numbers
 25* Easy access control
 26  - Allow/disallow anonymous access
 27  - Add collaborators with SSH public keys
 28  - Repos can be public or private
 29
 30## Where can I see it?
 31
 32Just run `ssh git.charm.sh` for an example. You can also try some of the following commands:
 33
 34```bash
 35# Jump directly to a repo in the TUI
 36ssh git.charm.sh -t soft-serve
 37
 38# Print out a directory tree for a repo
 39ssh git.charm.sh ls soft-serve
 40
 41# Print a specific file
 42ssh git.charm.sh cat soft-serve/cmd/soft/root.go
 43
 44# Print a file with syntax highlighting and line numbers
 45ssh git.charm.sh cat soft-serve/cmd/soft/root.go -c -l
 46```
 47
 48## Installation
 49
 50Soft Serve is a single binary called `soft`. You can get it from a package
 51manager:
 52
 53```bash
 54# macOS or Linux
 55brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
 56
 57# Arch Linux
 58pacman -S soft-serve
 59
 60# Nix
 61nix-env -iA nixpkgs.soft-serve
 62
 63# Debian/Ubuntu
 64sudo mkdir -p /etc/apt/keyrings
 65curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
 66echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
 67sudo apt update && sudo apt install soft-serve
 68
 69# Fedora/RHEL
 70echo '[charm]
 71name=Charm
 72baseurl=https://repo.charm.sh/yum/
 73enabled=1
 74gpgcheck=1
 75gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
 76sudo yum install soft-serve
 77```
 78
 79You can also download a binary from the [releases][releases] page. Packages are
 80available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
 81macOS, and Windows.
 82
 83[releases]: https://github.com/charmbracelet/soft-serve/releases
 84
 85Or just install it with `go`:
 86
 87```bash
 88go install github.com/charmbracelet/soft-serve/cmd/soft@latest
 89```
 90
 91## Setting up a server
 92
 93Make sure `git` is installed, then run `soft`. That’s it.
 94
 95A [Docker image][docker] is also available.
 96
 97[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
 98
 99## Configuration
100
101The Soft Serve configuration is simple and straightforward:
102
103```yaml
104# The name of the server to show in the TUI.
105name: Soft Serve
106
107# The host and port to display in the TUI. You may want to change this if your
108# server is accessible from a different host and/or port that what it's
109# actually listening on (for example, if it's behind a reverse proxy).
110host: localhost
111port: 23231
112
113# Access level for anonymous users. Options are: admin-access, read-write,
114# read-only, and no-access.
115anon-access: read-write
116
117# You can grant read-only access to users without private keys.
118allow-keyless: false
119
120# Customize repos in the menu
121repos:
122  - name: Home
123    repo: config
124    private: true
125    note: "Configuration and content repo for this server"
126  - name: Example Public Repo
127    repo: my-public-repo
128    private: false
129    note: "A publicly-accessible repo"
130    readme: docs/README.md
131  - name: Example Private Repo
132    repo: my-private-repo
133    private: true
134    note: "A private repo"
135
136# Authorized users. Admins have full access to all repos. Private repos are only
137# accessible by admins and collab users. Regular users can read public repos
138# based on your anon-access setting.
139users:
140  - name: Beatrice
141    admin: true
142    public-keys:
143      - ssh-rsa AAAAB3Nz...   # redacted
144      - ssh-ed25519 AAAA...   # redacted
145  - name: Frankie
146    collab-repos:
147      - my-public-repo
148      - my-private-repo
149    public-keys:
150      - ssh-rsa AAAAB3Nz...   # redacted
151      - ssh-ed25519 AAAA...   # redacted
152```
153
154When `soft serve` is run for the first time, it creates a configuration repo
155containing the main README displayed in the TUI as well as a config file for
156user access control.
157
158```
159git clone ssh://localhost:23231/config
160```
161
162The `config` repo is publicly writable by default, so be sure to setup your
163access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
164environment variable before first run and it will restrict access to that
165initial public key until you configure things otherwise.
166If you're having trouble, make sure you have generated keys with `ssh-keygen`
167as configuration is not supported for keyless users.
168
169### Server Settings
170
171In addition to the Git-based configuration above, there are a few
172environment-level settings:
173
174* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
175* `SOFT_SERVE_HOST`: Address to use in public clone URLs
176* `SOFT_SERVE_BIND_ADDRESS`: Network interface to listen on (_default 0.0.0.0_)
177* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
178* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
179* `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.
180
181## Pushing (and creating!) repos
182
183You can add your Soft Serve server as a remote to any existing repo:
184
185```
186git remote add soft ssh://localhost:23231/REPO
187```
188
189After you’ve added the remote just go ahead and push. If the repo doesn’t exist
190on the server it’ll be created.
191
192```
193git push soft main
194```
195
196## The Soft Serve TUI
197
198<img src="https://stuff.charm.sh/soft-serve/soft-serve-demo-commit.png" width="750" alt="TUI example showing a diff">
199
200Soft Serve serves a TUI over SSH for browsing repos, viewing files and commits,
201and grabbing clone commands:
202
203```
204ssh localhost -p 23231
205```
206
207It's also possible to “link” to a specific repo:
208
209```
210ssh localhost -t -p 23231 REPO
211```
212
213You can copy text to your clipboard over SSH. For instance, you can press <kbd>c</kbd> on the highlighted repo in the menu to copy the clone command [^osc52].
214
215[^osc52]: Copying over SSH depends on your terminal support of OSC52.
216
217## The Soft Serve SSH CLI
218
219```sh
220$ ssh -p 23231 localhost help
221Soft Serve is a self-hostable Git server for the command line.
222
223Usage:
224  ssh -p 23231 localhost [command]
225
226Available Commands:
227  cat         Outputs the contents of the file at path.
228  git         Perform Git operations on a repository.
229  help        Help about any command
230  ls          List file or directory at path.
231  reload      Reloads the configuration
232
233Flags:
234  -h, --help   help for ssh
235
236Use "ssh -p 23231 localhost [command] --help" for more information about a command.
237```
238
239Soft Serve SSH CLI has the ability to print files and list directories, perform
240`git` operations on remote repos, and reload the configuration when necessary.
241
242To print a file tree for the project, just use the `list` command along with the
243repo name as the SSH command to your Soft Serve server:
244
245```sh
246ssh -p 23231 localhost ls soft-serve
247```
248
249From there, you can print individual files using the `cat` command:
250
251```sh
252ssh -p 23231 localhost cat soft-serve/cmd/soft/root.go
253```
254
255You can add the `-c` flag to enable syntax coloring and `-l` to print line
256numbers:
257
258```sh
259ssh -p 23231 localhost cat soft-serve/cmd/soft/root.go -c -l
260```
261
262You can also use the `git` command to perform Git operations on a repo such as changing the default branch name for instance:
263
264```sh
265ssh -p 23231 localhost git soft-serve symbolic-ref HEAD refs/heads/taco
266```
267
268Both `git` and `reload` commands need admin access to the server to work. So
269make sure you have added your key as an admin user, or you’re using `anon-access:
270admin-access` in the configuration.
271
272## Managing Repos
273
274`.repos` and `.ssh` directories are created when you first run `soft` at the paths specified for the `SOFT_SERVE_KEY_PATH` and `SOFT_SERVE_REPO_PATH` environment variables. 
275It's recommended to have a dedicated directory for your soft-serve repos and config.
276
277### Deleting a Repo
278
279To delete a repo from your soft serve server, you'll have to remove the repo from the .repos directory.
280
281### Renaming a Repo
282
283To rename a repo's display name in the menu, change its name in the config.yaml file for your soft serve server.
284By default, the display name will be the repository name. 
285
286## A note about RSA keys
287
288Unfortunately, due to a shortcoming in Go’s `x/crypto/ssh` package, Soft Serve
289does not currently support access via new SSH RSA keys: only the old SHA-1
290ones will work.
291
292Until we sort this out you’ll either need an SHA-1 RSA key or a key with
293another algorithm, e.g. Ed25519. Not sure what type of keys you have?
294You can check with the following:
295
296```
297$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;
298```
299
300If you’re curious about the inner workings of this problem have a look at:
301
302- https://github.com/golang/go/issues/37278
303- https://go-review.googlesource.com/c/crypto/+/220037
304- https://github.com/golang/crypto/pull/197
305
306## Feedback
307
308We’d love to hear your thoughts on this project. Feel free to drop us a note!
309
310* [Twitter](https://twitter.com/charmcli)
311* [The Fediverse](https://mastodon.technology/@charm)
312* [Slack](https://charm.sh/slack)
313
314## License
315
316[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
317
318***
319
320Part of [Charm](https://charm.sh).
321
322<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
323
324Charm热爱开源 • Charm loves open source