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