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## Configuration
34
35The Soft Serve configuration is simple and straightforward:
36
37```yaml
38# The name of the server to show in the TUI.
39name: Soft Serve
40
41# The host and port to listen on. Defaults to 0.0.0.0:23231.
42host: localhost
43port: 23231
44
45# The access level for anonymous users. Options are: read-write, read-only
46# and no-access.
47anon-access: read-write
48
49# You can grant read-only access to users without private keys.
50allow-keyless: false
51
52# Which repos should appear in the menu?
53repos:
54 - name: Home
55 repo: config
56 private: true
57 note: "Configuration and content repo for this server"
58 - name: Example Public Repo
59 repo: my-public-repo
60 private: false
61 note: "A publicly-accessible repo"
62 - name: Example Private Repo
63 repo: my-private-repo
64 private: true
65 note: "A private repo"
66
67# Authorized users. Admins have full access to all repos. Regular users
68# can read all repos and push to their collab-repos.
69users:
70 - name: Beatrice
71 admin: true
72 public-keys:
73 - KEY TEXT
74 - name: Frankie
75 collab-repos:
76 - my-public-repo
77 - my-private-repo
78 public-keys:
79 - KEY TEXT
80```
81
82When `soft` is run for the first time, it creates a configuration repo
83containing the main README displayed in the TUI as well as a config file for
84user access control.
85
86```
87git clone ssh://localhost:23231/config
88```
89
90The `config` repo is publicly writable by default, so be sure to setup your
91access as desired. You can also set the `SOFT_SERVE_INITIAL_ADMIN_KEY`
92environment variable before first run and it will restrict access to that
93initial public key until you configure things otherwise.
94
95## Pushing (and creating!) repos
96
97You can add your Soft Serve server as a remote to any existing repo:
98
99```
100git remote add soft ssh://localhost:23231/REPO
101```
102
103After you’ve added the remote just go ahead and push. If the repo doesn’t exist
104on the server it’ll be created.
105
106```
107git push soft main
108```
109
110## The Soft Serve TUI
111
112Soft Serve serves a TUI over SSH for browsing repos, viewing READMEs, and
113grabbing clone commands:
114
115```
116ssh localhost -p 23231
117```
118
119It's also possible to “link” to a specific repo:
120
121```
122ssh localhost -t -p 23231 REPO
123```
124
125### Server Settings
126
127In addition to the Git-based configuration above, there are a few
128environment-level settings:
129
130* `SOFT_SERVE_PORT`: SSH listen port (_default 23231_)
131* `SOFT_SERVE_HOST`: SSH listen host (_default 0.0.0.0_)
132* `SOFT_SERVE_KEY_PATH`: SSH host key-pair path (_default .ssh/soft_serve_server_ed25519_)
133* `SOFT_SERVE_REPO_PATH`: Path where repos are stored (_default .repos_)
134* `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.