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