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