1# Soft Serve
2
3<p>
4 <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"><br>
5 <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>
6 <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>
7 <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>
8 <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>
9</p>
10
11A tasty, self-hostable Git server for the command line. š¦
12
13<picture>
14 <source media="(max-width: 750px)" srcset="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0">
15 <source media="(min-width: 750px)" width="750" srcset="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0">
16 <img src="https://stuff.charm.sh/soft-serve/soft-serve-demo.gif?0" alt="Soft Serve screencast">
17</picture>
18
19- Easy to navigate TUI available over SSH
20- Clone repos over SSH, HTTP, or Git protocol
21- Git LFS support with both HTTP and SSH backends
22- Manage repos with SSH
23- Create repos on demand with SSH or `git push`
24- Browse repos, files and commits with SSH-accessible UI
25- Print files over SSH with or without syntax highlighting and line numbers
26- Easy access control
27 - SSH authentication using public keys
28 - Allow/disallow anonymous access
29 - Add collaborators with SSH public keys
30 - Repos can be public or private
31 - User access tokens
32
33## Where can I see it?
34
35Just run `ssh git.charm.sh` for an example. You can also try some of the following commands:
36
37```bash
38# Jump directly to a repo in the TUI
39ssh git.charm.sh -t soft-serve
40
41# Print out a directory tree for a repo
42ssh git.charm.sh repo tree soft-serve
43
44# Print a specific file
45ssh git.charm.sh repo blob soft-serve cmd/soft/root.go
46
47# Print a file with syntax highlighting and line numbers
48ssh git.charm.sh repo blob soft-serve cmd/soft/root.go -c -l
49```
50
51## Installation
52
53Soft Serve is a single binary called `soft`. You can get it from a package
54manager:
55
56```bash
57# macOS or Linux
58brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve
59
60# Arch Linux
61pacman -S soft-serve
62
63# Nix
64nix-env -iA nixpkgs.soft-serve
65
66# Debian/Ubuntu
67sudo mkdir -p /etc/apt/keyrings
68curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
69echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
70sudo apt update && sudo apt install soft-serve
71
72# Fedora/RHEL
73echo '[charm]
74name=Charm
75baseurl=https://repo.charm.sh/yum/
76enabled=1
77gpgcheck=1
78gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
79sudo yum install soft-serve
80```
81
82You can also download a binary from the [releases][releases] page. Packages are
83available in Alpine, Debian, and RPM formats. Binaries are available for Linux,
84macOS, and Windows.
85
86[releases]: https://github.com/charmbracelet/soft-serve/releases
87
88Or just install it with `go`:
89
90```bash
91go install github.com/charmbracelet/soft-serve/cmd/soft@latest
92```
93
94A [Docker image][docker] is also available.
95
96[docker]: https://github.com/charmbracelet/soft-serve/blob/main/docker.md
97
98## Setting up a server
99
100Make sure `git` is installed, then run `soft serve`. Thatās it.
101
102This will create a `data` directory that will store all the repos, ssh keys,
103and database.
104
105To change the default data path use `SOFT_SERVE_DATA_PATH` environment variable.
106
107```sh
108SOFT_SERVE_DATA_PATH=/var/lib/soft-serve soft serve
109```
110
111When you run Soft Serve for the first time, make sure you have the
112`SOFT_SERVE_INITIAL_ADMIN_KEYS` environment variable is set to your ssh
113authorized key. Any added key to this variable will be treated as admin with
114full privileges.
115
116Using this environment variable, Soft Serve will create a new `admin` user that
117has full privileges. You can rename and change the user settings later.
118
119Check out [Systemd][systemd] on how to run Soft Serve as a service using
120Systemd. Soft Serve packages in our Apt/Yum repositories come with Systemd
121service units.
122
123[systemd]: https://github.com/charmbracelet/soft-serve/blob/main/systemd.md
124
125### Server Configuration
126
127Once you start the server for the first time, the settings will be in
128`config.yaml` under your data directory. The default `config.yaml` is
129self-explanatory and will look like this:
130
131```yaml
132# Soft Serve Server configurations
133
134# The name of the server.
135# This is the name that will be displayed in the UI.
136name: "Soft Serve"
137
138# Log format to use. Valid values are "json", "logfmt", and "text".
139log_format: "text"
140
141# The SSH server configuration.
142ssh:
143 # The address on which the SSH server will listen.
144 listen_addr: ":23231"
145
146 # The public URL of the SSH server.
147 # This is the address that will be used to clone repositories.
148 public_url: "ssh://localhost:23231"
149
150 # The path to the SSH server's private key.
151 key_path: "ssh/soft_serve_host"
152
153 # The path to the SSH server's client private key.
154 # This key will be used to authenticate the server to make git requests to
155 # ssh remotes.
156 client_key_path: "ssh/soft_serve_client"
157
158 # The maximum number of seconds a connection can take.
159 # A value of 0 means no timeout.
160 max_timeout: 0
161
162 # The number of seconds a connection can be idle before it is closed.
163 idle_timeout: 120
164
165# The Git daemon configuration.
166git:
167 # The address on which the Git daemon will listen.
168 listen_addr: ":9418"
169
170 # The maximum number of seconds a connection can take.
171 # A value of 0 means no timeout.
172 max_timeout: 0
173
174 # The number of seconds a connection can be idle before it is closed.
175 idle_timeout: 3
176
177 # The maximum number of concurrent connections.
178 max_connections: 32
179
180# The HTTP server configuration.
181http:
182 # The address on which the HTTP server will listen.
183 listen_addr: ":23232"
184
185 # The path to the TLS private key.
186 tls_key_path: ""
187
188 # The path to the TLS certificate.
189 tls_cert_path: ""
190
191 # The public URL of the HTTP server.
192 # This is the address that will be used to clone repositories.
193 # Make sure to use https:// if you are using TLS.
194 public_url: "http://localhost:23232"
195
196# The database configuration.
197db:
198 # The database driver to use.
199 # Valid values are "sqlite" and "postgres".
200 driver: "sqlite"
201 # The database data source name.
202 # This is driver specific and can be a file path or connection string.
203 data_source: "soft-serve.db"
204
205# Git LFS configuration.
206lfs:
207 # Enable Git LFS.
208 enabled: true
209 # Enable Git SSH transfer.
210 ssh_enabled: true
211
212# The stats server configuration.
213stats:
214 # The address on which the stats server will listen.
215 listen_addr: ":23233"
216# Additional admin keys.
217#initial_admin_keys:
218# - "ssh-rsa AAAAB3NzaC1yc2..."
219```
220
221You can also use environment variables, to override these settings. All server
222settings environment variables start with `SOFT_SERVE_` followed by the setting
223name all in uppercase. Here are some examples:
224
225- `SOFT_SERVE_NAME`: The name of the server that will appear in the TUI
226- `SOFT_SERVE_SSH_LISTEN_ADDR`: SSH listen address
227- `SOFT_SERVE_SSH_KEY_PATH`: SSH host key-pair path
228- `SOFT_SERVE_HTTP_LISTEN_ADDR`: HTTP listen address
229- `SOFT_SERVE_HTTP_PUBLIC_URL`: HTTP public URL used for cloning
230- `SOFT_SERVE_GIT_MAX_CONNECTIONS`: The number of simultaneous connections to git daemon
231
232#### Database Configuration
233
234Soft Serve supports both SQLite and Postgres for its database. Like all other Soft Serve settings, you can change the database _driver_ and _data source_ using either `config.yaml` or environment variables. The default config uses SQLite as the default database driver.
235
236To use Postgres as your database, first create a Soft Serve database:
237
238```sh
239psql -h<hostname> -p<port> -U<user> -c 'CREATE DATABASE soft_serve'
240```
241
242Then set the database _data source_ to point to your Postgres database. For instance, if you're running Postgres locally, using the default user `postgres` and using a database name `soft_serve`, you would have this config in your config file or environment variable:
243
244```
245db:
246 driver: "postgres"
247 data_source: "postgres://postgres@localhost:5432/soft_serve?sslmode=disable"
248```
249
250Environment variables equivalent:
251
252```sh
253SOFT_SERVE_DB_DRIVER=postgres \
254SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres@localhost:5432/soft_serve?sslmode=disable" \
255soft serve
256```
257
258You can specify a database connection password in the _data source_ url. For example, `postgres://myuser:dbpass@localhost:5432/my_soft_serve_db`.
259
260#### LFS Configuration
261
262Soft Serve supports both Git LFS [HTTP](https://github.com/git-lfs/git-lfs/blob/main/docs/api/README.md) and [SSH](https://github.com/git-lfs/git-lfs/blob/main/docs/proposals/ssh_adapter.md) protocols out of the box, there is no need to do any extra set up.
263
264Use the `lfs` config section to customize your Git LFS server.
265
266## Server Access
267
268Soft Serve at its core manages your server authentication and authorization. Authentication verifies the identity of a user, while authorization determines their access rights to a repository.
269
270To manage the server users, access, and repos, you can use the SSH command line interface.
271
272Try `ssh localhost -i ~/.ssh/id_ed25519 -p 23231 help` for more info. Make sure
273you use your key here.
274
275For ease of use, instead of specifying the key, port, and hostname every time
276you SSH into Soft Serve, add your own Soft Serve instance entry to your SSH
277config. For instance, to use `ssh soft` instead of typing `ssh localhost -i
278~/.ssh/id_ed25519 -p 23231`, we can define a `soft` entry in our SSH config
279file `~/.ssh/config`.
280
281```conf
282Host soft
283 HostName localhost
284 Port 23231
285 IdentityFile ~/.ssh/id_ed25519
286```
287
288Now, we can do `ssh soft` to SSH into Soft Serve. Since `git` is also aware of
289this config, you can use `soft` as the hostname for your clone commands.
290
291```sh
292git clone ssh://soft/dotfiles
293# make changes
294# add & commit
295git push origin main
296```
297
298> **Note** The `-i` part will be omitted in the examples below for brevity. You
299> can add your server settings to your sshconfig for quicker access.
300
301### Authentication
302
303Everything that needs authentication is done using SSH. Make sure you have
304added an entry for your Soft Serve instance in your `~/.ssh/config` file.
305
306By default, Soft Serve gives ready-only permission to anonymous connections to
307any of the above protocols. This is controlled by two settings `anon-access`
308and `allow-keyless`.
309
310- `anon-access`: Defines the access level for anonymous users. Available
311 options are `no-access`, `read-only`, `read-write`, and `admin-access`.
312 Default is `read-only`.
313- `allow-keyless`: Whether to allow connections that doesn't use keys to pass.
314 Setting this to `false` would disable access to SSH keyboard-interactive,
315 HTTP, and Git protocol connections. Default is `true`.
316
317```sh
318$ ssh -p 23231 localhost settings
319Manage server settings
320
321Usage:
322 ssh -p 23231 localhost settings [command]
323
324Available Commands:
325 allow-keyless Set or get allow keyless access to repositories
326 anon-access Set or get the default access level for anonymous users
327
328Flags:
329 -h, --help help for settings
330
331Use "ssh -p 23231 localhost settings [command] --help" for more information about a command.
332```
333
334> **Note** These settings can only be changed by admins.
335
336When `allow-keyless` is disabled, connections that don't use SSH Public Key
337authentication will get denied. This means cloning repos over HTTP(s) or git://
338will get denied.
339
340Meanwhile, `anon-access` controls the access level granted to connections that
341use SSH Public Key authentication but are not registered users. The default
342setting for this is `read-only`. This will grant anonymous connections that use
343SSH Public Key authentication `read-only` access to public repos.
344
345`anon-access` is also used in combination with `allow-keyless` to determine the
346access level for HTTP(s) and git:// clone requests.
347
348#### SSH
349
350Soft Serve doesn't allow duplicate SSH public keys for users. A public key can be associated with one user only. This makes SSH authentication simple and straight forward, add your public key to your Soft Serve user to be able to access Soft Serve.
351
352#### HTTP
353
354You can generate user access tokens through the SSH command line interface. Access tokens can have an optional expiration date. Use your access token as the basic auth user to access your Soft Serve repos through HTTP.
355
356```sh
357# Create a user token
358ssh -p 23231 localhost token create 'my new token'
359ss_1234abc56789012345678901234de246d798fghi
360
361# Or with an expiry date
362ssh -p 23231 localhost token create --expires-in 1y 'my other token'
363ss_98fghi1234abc56789012345678901234de246d7
364```
365
366Now you can access to repos that require `read-write` access.
367
368```sh
369git clone http://ss_98fghi1234abc56789012345678901234de246d7@localhost:23232/my-private-repo.git my-private-repo
370# Make changes and push
371```
372
373### Authorization
374
375Soft Serve offers a simple access control. There are four access levels,
376no-access, read-only, read-write, and admin-access.
377
378`admin-access` has full control of the server and can make changes to users and repos.
379
380`read-write` access gets full control of repos.
381
382`read-only` can read public repos.
383
384`no-access` denies access to all repos.
385
386## User Management
387
388Admins can manage users and their keys using the `user` command. Once a user is
389created and has access to the server, they can manage their own keys and
390settings.
391
392To create a new user simply use `user create`:
393
394```sh
395# Create a new user
396ssh -p 23231 localhost user create beatrice
397
398# Add user keys
399ssh -p 23231 localhost user add-pubkey beatrice ssh-rsa AAAAB3Nz...
400ssh -p 23231 localhost user add-pubkey beatrice ssh-ed25519 AAAA...
401
402# Create another user with public key
403ssh -p 23231 localhost user create frankie '-k "ssh-ed25519 AAAATzN..."'
404
405# Need help?
406ssh -p 23231 localhost user help
407```
408
409Once a user is created, they get `read-only` access to public repositories.
410They can also create new repositories on the server.
411
412Users can manage their keys using the `pubkey` command:
413
414```sh
415# List user keys
416ssh -p 23231 localhost pubkey list
417
418# Add key
419ssh -p 23231 localhost pubkey add ssh-ed25519 AAAA...
420
421# Wanna change your username?
422ssh -p 23231 localhost set-username yolo
423
424# To display user info
425ssh -p 23231 localhost info
426```
427
428## Repositories
429
430You can manage repositories using the `repo` command.
431
432```sh
433# Run repo help
434$ ssh -p 23231 localhost repo help
435Manage repositories
436
437Usage:
438 ssh -p 23231 localhost repo [command]
439
440Aliases:
441 repo, repos, repository, repositories
442
443Available Commands:
444 blob Print out the contents of file at path
445 branch Manage repository branches
446 collab Manage collaborators
447 create Create a new repository
448 delete Delete a repository
449 description Set or get the description for a repository
450 hide Hide or unhide a repository
451 import Import a new repository from remote
452 info Get information about a repository
453 is-mirror Whether a repository is a mirror
454 list List repositories
455 private Set or get a repository private property
456 project-name Set or get the project name for a repository
457 rename Rename an existing repository
458 tag Manage repository tags
459 tree Print repository tree at path
460
461Flags:
462 -h, --help help for repo
463
464Use "ssh -p 23231 localhost repo [command] --help" for more information about a command.
465```
466
467To use any of the above `repo` commands, a user must be a collaborator in the repository. More on this below.
468
469### Creating Repositories
470
471To create a repository, first make sure you are a registered user. Use the
472`repo create <repo>` command to create a new repository:
473
474```sh
475# Create a new repository
476ssh -p 23231 localhost repo create icecream
477
478# Create a repo with description
479ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"'
480
481# ... and project name
482ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' '-n "Ice Cream"'
483
484# I need my repository private!
485ssh -p 23231 localhost repo create icecream -p '-d "This is an Ice Cream description"' '-n "Ice Cream"'
486
487# Help?
488ssh -p 23231 localhost repo create -h
489```
490
491Or you can add your Soft Serve server as a remote to any existing repo, given
492you have write access, and push to remote:
493
494```
495git remote add origin ssh://localhost:23231/icecream
496```
497
498After youāve added the remote just go ahead and push. If the repo doesnāt exist
499on the server itāll be created.
500
501```
502git push origin main
503```
504
505Repositories can be nested too:
506
507```sh
508# Create a new nested repository
509ssh -p 23231 localhost repo create charmbracelet/icecream
510
511# Or ...
512git remote add charm ssh://localhost:23231/charmbracelet/icecream
513git push charm main
514```
515
516### Deleting Repositories
517
518You can delete repositories using the `repo delete <repo>` command.
519
520```sh
521ssh -p 23231 localhost repo delete icecream
522```
523
524### Renaming Repositories
525
526Use the `repo rename <old> <new>` command to rename existing repositories.
527
528```sh
529ssh -p 23231 localhost repo rename icecream vanilla
530```
531
532### Repository Collaborators
533
534Sometimes you want to restrict write access to certain repositories. This can
535be achieved by adding a collaborator to your repository.
536
537Use the `repo collab <command> <repo>` command to manage repo collaborators.
538
539```sh
540# Add collaborator to soft-serve
541ssh -p 23231 localhost repo collab add soft-serve frankie
542
543# Add collaborator with a specific access level
544ssh -p 23231 localhost repo collab add soft-serve beatrice read-only
545
546# Remove collaborator
547ssh -p 23231 localhost repo collab remove soft-serve beatrice
548
549# List collaborators
550ssh -p 23231 localhost repo collab list soft-serve
551```
552
553### Repository Metadata
554
555You can also change the repo's description, project name, whether it's private,
556etc using the `repo <command>` command.
557
558```sh
559# Set description for repo
560ssh -p 23231 localhost repo description icecream "This is a new description"
561
562# Hide repo from listing
563ssh -p 23231 localhost repo hidden icecream true
564
565# List repository info (branches, tags, description, etc)
566ssh -p 23231 localhost repo icecream info
567```
568
569To make a repository private, use `repo private <repo> [true|false]`. Private
570repos can only be accessed by admins and collaborators.
571
572```sh
573ssh -p 23231 localhost repo icecream private true
574```
575
576### Repository Branches & Tags
577
578Use `repo branch` and `repo tag` to list, and delete branches or tags. You can
579also use `repo branch default` to set or get the repository default branch.
580
581### Repository Tree
582
583To print a file tree for the project, just use the `repo tree` command along with
584the repo name as the SSH command to your Soft Serve server:
585
586```sh
587ssh -p 23231 localhost repo tree soft-serve
588```
589
590You can also specify the sub-path and a specific reference or branch.
591
592```sh
593ssh -p 23231 localhost repo tree soft-serve server/config
594ssh -p 23231 localhost repo tree soft-serve main server/config
595```
596
597From there, you can print individual files using the `repo blob` command:
598
599```sh
600ssh -p 23231 localhost repo blob soft-serve cmd/soft/root.go
601```
602
603You can add the `-c` flag to enable syntax coloring and `-l` to print line
604numbers:
605
606```sh
607ssh -p 23231 localhost repo blob soft-serve cmd/soft/root.go -c -l
608
609```
610
611Use `--raw` to print raw file contents. This is useful for dumping binary data.
612
613## The Soft Serve TUI
614
615<img src="https://stuff.charm.sh/soft-serve/soft-serve-demo-commit.png" width="750" alt="TUI example showing a diff">
616
617Soft Serve serves a TUI over SSH for browsing repos, viewing files and commits,
618and grabbing clone commands:
619
620```sh
621ssh localhost -p 23231
622```
623
624It's also possible to ālinkā to a specific repo:
625
626```sh
627ssh -p 23231 localhost -t soft-serve
628```
629
630You can copy text to your clipboard over SSH. For instance, you can press
631<kbd>c</kbd> on the highlighted repo in the menu to copy the clone command
632[^osc52].
633
634[^osc52]:
635 Copying over SSH depends on your terminal support of OSC52. Refer to
636 [go-osc52](https://github.com/aymanbagabas/go-osc52) for more information.
637
638## Hooks
639
640Soft Serve supports git server-side hooks `pre-receive`, `update`,
641`post-update`, and `post-receive`. This means you can define your own hooks to
642run on repository push events. Hooks can be defined as a per-repository hook,
643and/or global hooks that run for all repositories.
644
645You can find per-repository hooks under the repository `hooks` directory.
646
647Globs hooks can be found in your `SOFT_SERVE_DATA_PATH` directory under
648`hooks`. Defining global hooks is useful if you want to run CI/CD for example.
649
650Here's an example of sending a message after receiving a push event. Create an
651executable file `<data path>/hooks/update`:
652
653```sh
654#!/bin/sh
655#
656# An example hook script to echo information about the push
657# and send it to the client.
658
659refname="$1"
660oldrev="$2"
661newrev="$3"
662
663# Safety check
664if [ -z "$GIT_DIR" ]; then
665 echo "Don't run this script from the command line." >&2
666 echo " (if you want, you could supply GIT_DIR then run" >&2
667 echo " $0 <ref> <oldrev> <newrev>)" >&2
668 exit 1
669fi
670
671if [ -z "$refname" -o -z "$oldrev" -o -z "$newrev" ]; then
672 echo "usage: $0 <ref> <oldrev> <newrev>" >&2
673 exit 1
674fi
675
676# Check types
677# if $newrev is 0000...0000, it's a commit to delete a ref.
678zero=$(git hash-object --stdin </dev/null | tr '[0-9a-f]' '0')
679if [ "$newrev" = "$zero" ]; then
680 newrev_type=delete
681else
682 newrev_type=$(git cat-file -t $newrev)
683fi
684
685echo "Hi from Soft Serve update hook!"
686echo
687echo "RefName: $refname"
688echo "Change Type: $newrev_type"
689echo "Old SHA1: $oldrev"
690echo "New SHA1: $newrev"
691
692exit 0
693```
694
695Now, you should get a message after pushing changes to any repository.
696
697## A note about RSA keys
698
699Unfortunately, due to a shortcoming in Goās `x/crypto/ssh` package, Soft Serve
700does not currently support access via new SSH RSA keys: only the old SHA-1
701ones will work.
702
703Until we sort this out youāll either need an SHA-1 RSA key or a key with
704another algorithm, e.g. Ed25519. Not sure what type of keys you have?
705You can check with the following:
706
707```sh
708$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;
709```
710
711If youāre curious about the inner workings of this problem have a look at:
712
713- https://github.com/golang/go/issues/37278
714- https://go-review.googlesource.com/c/crypto/+/220037
715- https://github.com/golang/crypto/pull/197
716
717## Feedback
718
719Weād love to hear your thoughts on this project. Feel free to drop us a note!
720
721- [Twitter](https://twitter.com/charmcli)
722- [The Fediverse](https://mastodon.social/@charmcli)
723- [Discord](https://charm.sh/chat)
724
725## License
726
727[MIT](https://github.com/charmbracelet/soft-serve/raw/main/LICENSE)
728
729---
730
731Part of [Charm](https://charm.sh).
732
733<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
734
735Charmēē±å¼ęŗ ā¢ Charm loves open source