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-hosted 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## Building/installing
 30
 31The Soft Serve command is called `soft`. You can build and install it with
 32`go`:
 33
 34```bash
 35git clone ssh://git.charm.sh/soft-serve
 36cd soft-serve
 37go install
 38```
 39
 40## Setting up a server
 41
 42Make sure `git` is installed, then run `soft`. That’s it.
 43
 44A [Docker image](https://github.com/charmbracelet/soft-serve/blob/main/DOCKER.md) is also available.
 45
 46## Configuration
 47
 48The Soft Serve configuration is simple and straightforward:
 49
 50```yaml
 51# The name of the server to show in the TUI.
 52name: Soft Serve
 53
 54# The host and port to listen on. Defaults to 0.0.0.0:23231.
 55host: localhost
 56port: 23231
 57
 58# The access level for anonymous users. Options are: read-write, read-only
 59# and no-access.
 60anon-access: read-write
 61
 62# You can grant read-only access to users without private keys.
 63allow-keyless: false
 64
 65# Which repos should appear in the menu?
 66repos:
 67  - name: Home
 68    repo: config
 69    private: true
 70    note: "Configuration and content repo for this server"
 71  - name: Example Public Repo
 72    repo: my-public-repo
 73    private: false
 74    note: "A publicly-accessible repo"
 75  - name: Example Private Repo
 76    repo: my-private-repo
 77    private: true
 78    note: "A private repo"
 79
 80# Authorized users. Admins have full access to all repos. Regular users
 81# can read all repos and push to their collab-repos.
 82users:
 83  - name: Beatrice
 84    admin: true
 85    public-keys:
 86      - KEY TEXT
 87  - name: Frankie
 88    collab-repos:
 89      - my-public-repo
 90      - my-private-repo
 91    public-keys:
 92      - KEY TEXT
 93```
 94
 95When `soft` is run for the first time, it creates a configuration repo
 96containing the main README displayed in the TUI as well as a config file for
 97user access control.
 98
 99```
100git clone ssh://localhost:23231/config
101```
102
103The `config` repo is publicly writable by default, so be sure to setup your
104access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
105environment variable before first run and it will restrict access to that
106initial public key until you configure things otherwise.
107
108## Pushing (and creating!) repos
109
110You can add your Soft Serve server as a remote to any existing repo:
111
112```
113git remote add soft ssh://localhost:23231/REPO
114```
115
116After you’ve added the remote just go ahead and push. If the repo doesn’t exist
117on the server it’ll be created.
118
119```
120git push soft main
121```
122
123## The Soft Serve TUI
124
125Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
126grabbing clone commands:
127
128```
129ssh localhost -p 23231
130```
131
132It's also possible to “link” to a specific repo:
133
134```
135ssh localhost -t -p 23231 REPO
136```
137
138### Server Settings
139
140In addition to the Git-based configuration above, there are a few
141environment-level settings:
142
143* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
144* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
145* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
146* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
147* `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.
148
149## License
150
151[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
152
153***
154
155Part of [Charm](https://charm.sh).
156
157<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
158
159Charm热爱开源 • Charm loves open source