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