From b3efb276b33a222750b0d1344d47716db45f001e Mon Sep 17 00:00:00 2001
From: Justin Wernick <justin@worthe-it.co.za>
Date: Sat, 29 Apr 2023 21:59:37 +0200
Subject: Finish filling in details in the readme

---
 readme.org | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 55 insertions(+), 8 deletions(-)

(limited to 'readme.org')

diff --git a/readme.org b/readme.org
index cbb61db..32f75af 100644
--- a/readme.org
+++ b/readme.org
@@ -88,17 +88,64 @@ all of the options, and is a great way to learn what all the commands do.
 
 ** Installation
 
+*** Prerequisites
+
+- Git
+  - This is used for git operations which are passed through for the operation
+    of =git push= and =git fetch=.
+  - Git must be installed, with the =git-upload-pack= and =git-receive-pack=
+    executables on the path.
+- SSH
+  - I assume users will be connecting over SSH. This is not enforced by the
+    shell, but is the primary use case I have in mind. I have tested this using
+    the OpenSSH daemon.
+
+*** Building Shackle
+
+There is not yet a binary release of Shackle, so you need to build it yourself
+from source. The easiest way to do this is using =cargo install=.
+
+This requires a the Rust toolchain and a C compiler. See the Development
+Environment Setup section below for more information on environment setup to
+build from source.
+
+#+begin_src sh
+  # This installs to Cargo's default, which is ~/.cargo/bin. Consider using the
+  # --root option to install it somewhere that makes more sense for your server.
+  cargo install --git https://code.worthe-it.co.za/shackle.git/ --force
+#+end_src
+
+*** Creating the required directory structure
+
+Next, Shackle expects a specific directory structure. Specifically, personal git
+repos will live in =~/git/your-username= and shared repos will live in
+=~/git/your-group=.
+
+If you have many users on your server, then consider making =~/git= a symlink to
+the actual shared location for your git repos. For example, on my repo, all git
+users have a =~/git= symlink in their home directory which actually points at
+=/srv/git=.
+
 #+begin_src sh
-  cargo install --git https://code.worthe-it.co.za/shackle.git/ --root /opt/bin/shackle --force
+  mkdir -p ~/git/$USER
+  chmod --recursive u=rwX,g=,o= ~/git/$USER
+
+  # Note that this should be a group you're actually a member of!
+  GROUP=my-group
+  mkdir -p ~/git/$GROUP
+  chown --recursive $USER:$GROUP ~/git/$GROUP
+  chmod --recursive u=rwX,g=rwXs,o= ~/git/$GROUP
 #+end_src
 
-# TODO
+*** Set Shackle as your default shell
+
+The next step is to set the default shell of your user to Shackle. This will
+mean that if you login as the user, for example over ssh, then the default shell
+will be Shackle.
 
-# - cargo install to build from source
-# - set as the user's shell
-# - create the appropriate directory structure
-# - requires git installed on the server
-# - I assume users will be connecting over SSH. This is not enforced by the shell.
+#+begin_src sh
+  sudo usermod --shell $HOME/.cargo/bin/shackle $USER
+#+end_src
 
 * Operating System Support
 
@@ -221,7 +268,7 @@ After running this, the binary is available in =./target/release/shackle=
 ** Post-MVP
 
 - [X] proper licensing
-- [ ] all the getting started stuff in the readme
+- [X] all the getting started stuff in the readme
 - [ ] clean up crates.io-friendly readme
   - It needs to be markdown, and probably not all the content of the "full" readme?
 - [ ] consider having the workspace root abstract so that --workspace isn't needed
-- 
cgit v1.2.3