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 Git server that runs its own SSH service. 🍦
 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
 44## Docker
 45
 46Here are some example snippets to help you run `soft-serve` as a container.
 47
 48```sh
 49docker run -d \
 50  --name=soft-seve \
 51  -v /path/to/data:/soft-serve \
 52  -p 23231:23231 \
 53  --restart unless-stopped \
 54  charmcli/soft-serve:latest
 55```
 56
 57or by using docker-compose:
 58
 59```yaml
 60---
 61version: "3.1"
 62services:
 63  soft-serve:
 64    image: charmcli/soft-serve:latest
 65    container_name: soft-serve
 66    volumes:
 67      - /path/to/data:/soft-serve
 68    ports:
 69      - 23231:23231
 70    restart: unless-stopped
 71```
 72
 73## Configuration
 74
 75The Soft Serve configuration is simple and straightforward:
 76
 77```yaml
 78# The name of the server to show in the TUI.
 79name: Soft Serve
 80
 81# The host and port to listen on. Defaults to 0.0.0.0:23231.
 82host: localhost
 83port: 23231
 84
 85# The access level for anonymous users. Options are: read-write, read-only
 86# and no-access.
 87anon-access: read-write
 88
 89# You can grant read-only access to users without private keys.
 90allow-keyless: false
 91
 92# Which repos should appear in the menu?
 93repos:
 94  - name: Home
 95    repo: config
 96    private: true
 97    note: "Configuration and content repo for this server"
 98  - name: Example Public Repo
 99    repo: my-public-repo
100    private: false
101    note: "A publicly-accessible repo"
102  - name: Example Private Repo
103    repo: my-private-repo
104    private: true
105    note: "A private repo"
106
107# Authorized users. Admins have full access to all repos. Regular users
108# can read all repos and push to their collab-repos.
109users:
110  - name: Beatrice
111    admin: true
112    public-keys:
113      - KEY TEXT
114  - name: Frankie
115    collab-repos:
116      - my-public-repo
117      - my-private-repo
118    public-keys:
119      - KEY TEXT
120```
121
122When `soft` is run for the first time, it creates a configuration repo
123containing the main README displayed in the TUI as well as a config file for
124user access control.
125
126```
127git clone ssh://localhost:23231/config
128```
129
130The `config` repo is publicly writable by default, so be sure to setup your
131access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
132environment variable before first run and it will restrict access to that
133initial public key until you configure things otherwise.
134
135## Pushing (and creating!) repos
136
137You can add your Soft Serve server as a remote to any existing repo:
138
139```
140git remote add soft ssh://localhost:23231/REPO
141```
142
143After you’ve added the remote just go ahead and push. If the repo doesn’t exist
144on the server it’ll be created.
145
146```
147git push soft main
148```
149
150## The Soft Serve TUI
151
152Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
153grabbing clone commands:
154
155```
156ssh localhost -p 23231
157```
158
159It's also possible to “link” to a specific repo:
160
161```
162ssh localhost -t -p 23231 REPO
163```
164
165### Server Settings
166
167In addition to the Git-based configuration above, there are a few
168environment-level settings:
169
170* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
171* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
172* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
173* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
174* `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.
175
176## License
177
178[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
179
180***
181
182<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
183
184Charm热爱开源 • Charm loves open source