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