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://github.com/charmbracelet/soft-serve/actions"><img src="https://github.com/charmbracelet/soft-serve/workflows/build/badge.svg" alt="Build Status"></a>
 11</p>
 12
 13A tasty, self-hostable Git server for the command line. 🍦
 14
 15<img src="https://stuff.charm.sh/soft-serve/soft-serve-cli-demo.gif" width="700" alt="Soft Serve screencast">
 16
 17* Configure with `git`
 18* Create repos on demand with `git push`
 19* Browse repos with an SSH-accessible TUI
 20* Easy access control
 21  - Allow/disallow anonymous access
 22  - Add collaborators with SSH public keys
 23  - Repos can be public or private
 24
 25## Where can I see it?
 26
 27Just run `ssh git.charm.sh` for an example.
 28
 29## Installation
 30
 31Soft Serve is a single binary called `soft`. You can get it from a package
 32manager:
 33
 34```bash
 35# macOS or Linux
 36brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
 37
 38# Arch Linux
 39yay -S soft-serve
 40```
 41
 42You can also download a binary from the [releases][releases] page. Packages are
 43available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
 44macOS, and Windows.
 45
 46[releases]: https://github.com/charmbracelet/soft-serve/releases
 47
 48Or just install it with `go`:
 49
 50```bash
 51go install github.com/charmbracelet/soft-serve/cmd/soft@latest
 52```
 53
 54## Setting up a server
 55
 56Make sure `git` is installed, then run `soft`. That’s it.
 57
 58A [Docker image][docker] is also available.
 59
 60[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
 61
 62## Configuration
 63
 64The Soft Serve configuration is simple and straightforward:
 65
 66```yaml
 67# The name of the server to show in the TUI.
 68name: Soft Serve
 69
 70# The host and port to listen on. Defaults to 0.0.0.0:23231.
 71host: localhost
 72port: 23231
 73
 74# The access level for anonymous users. Options are: read-write, read-only
 75# and no-access.
 76anon-access: read-write
 77
 78# You can grant read-only access to users without private keys.
 79allow-keyless: false
 80
 81# Which repos should appear in the menu?
 82repos:
 83  - name: Home
 84    repo: config
 85    private: true
 86    note: "Configuration and content repo for this server"
 87  - name: Example Public Repo
 88    repo: my-public-repo
 89    private: false
 90    note: "A publicly-accessible repo"
 91  - name: Example Private Repo
 92    repo: my-private-repo
 93    private: true
 94    note: "A private repo"
 95
 96# Authorized users. Admins have full access to all repos. Regular users
 97# can read all repos and push to their collab-repos.
 98users:
 99  - name: Beatrice
100    admin: true
101    public-keys:
102      - KEY TEXT
103  - name: Frankie
104    collab-repos:
105      - my-public-repo
106      - my-private-repo
107    public-keys:
108      - KEY TEXT
109```
110
111When `soft` is run for the first time, it creates a configuration repo
112containing the main README displayed in the TUI as well as a config file for
113user access control.
114
115```
116git clone ssh://localhost:23231/config
117```
118
119The `config` repo is publicly writable by default, so be sure to setup your
120access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
121environment variable before first run and it will restrict access to that
122initial public key until you configure things otherwise.
123
124## Pushing (and creating!) repos
125
126You can add your Soft Serve server as a remote to any existing repo:
127
128```
129git remote add soft ssh://localhost:23231/REPO
130```
131
132After you’ve added the remote just go ahead and push. If the repo doesn’t exist
133on the server it’ll be created.
134
135```
136git push soft main
137```
138
139## The Soft Serve TUI
140
141Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
142grabbing clone commands:
143
144```
145ssh localhost -p 23231
146```
147
148It's also possible to “link” to a specific repo:
149
150```
151ssh localhost -t -p 23231 REPO
152```
153
154### Server Settings
155
156In addition to the Git-based configuration above, there are a few
157environment-level settings:
158
159* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
160* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
161* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
162* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
163* `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.
164
165## License
166
167[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
168
169***
170
171Part of [Charm](https://charm.sh).
172
173<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
174
175Charm热爱开源 • Charm loves open source