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