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      - KEY TEXT
107  - name: Frankie
108    collab-repos:
109      - my-public-repo
110      - my-private-repo
111    public-keys:
112      - KEY TEXT
113```
114
115When `soft` is run for the first time, it creates a configuration repo
116containing the main README displayed in the TUI as well as a config file for
117user access control.
118
119```
120git clone ssh://localhost:23231/config
121```
122
123The `config` repo is publicly writable by default, so be sure to setup your
124access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
125environment variable before first run and it will restrict access to that
126initial public key until you configure things otherwise.
127
128## Pushing (and creating!) repos
129
130You can add your Soft Serve server as a remote to any existing repo:
131
132```
133git remote add soft ssh://localhost:23231/REPO
134```
135
136After you’ve added the remote just go ahead and push. If the repo doesn’t exist
137on the server it’ll be created.
138
139```
140git push soft main
141```
142
143## The Soft Serve TUI
144
145Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
146grabbing clone commands:
147
148```
149ssh localhost -p 23231
150```
151
152It's also possible to “link” to a specific repo:
153
154```
155ssh localhost -t -p 23231 REPO
156```
157
158### Server Settings
159
160In addition to the Git-based configuration above, there are a few
161environment-level settings:
162
163* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
164* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
165* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
166* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
167* `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.
168
169## License
170
171[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
172
173***
174
175Part of [Charm](https://charm.sh).
176
177<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
178
179Charm热爱开源 • Charm loves open source