From 4130d113ba5e0d9f666d5e528a30bed291692204 Mon Sep 17 00:00:00 2001
From: Adrian Amaglio <adrian@amaglio.fr>
Date: Mon, 15 Feb 2021 12:37:59 +0100
Subject: [PATCH] doc

---
 test-python-ssh/Readme.md | 71 +++++++++++++++++++++------------------
 1 file changed, 39 insertions(+), 32 deletions(-)

diff --git a/test-python-ssh/Readme.md b/test-python-ssh/Readme.md
index 9e22f82..a085b8d 100644
--- a/test-python-ssh/Readme.md
+++ b/test-python-ssh/Readme.md
@@ -1,35 +1,31 @@
 # Python, web and SSH sandbox
-For educational purpose only! None of this software is industry grade quality.  
+**For educational purpose only! None of this software is industry grade quality.**  
 
-This repo got several parts :
-
-## A python script
-It run with uwsgi, see the dockerfile CMD line. You will need to change it to make it listen on a port.
-Used to execute any python script in the `module` directory given a certain URL :
-- /m1/f1 -> execute the f1 function from modules/m1.py
-- /path/to/m2/f2 -> execute the f2 function from modules/path/to/m2.py
-
-## SSH server
-Allow student to connect via SSH or SFTP to add python files.
-create a file named `users.txt`, then passwords and accounts will be generated by `entrypoint.sh`
-TODO:
-- install and configure the server
-- configure chroot
-- create the homes in modules directory
-
-## A docker image
-To bundle everything in one place.
-This docker image is not a pretty one, we should split those services into several containers.
-But that would be harder to run, so forget that.  
-Also, as this is poorly tested, the docker system make sure the environment is stable.
-
-# Instructions
+# How to use it?
 ## Install docker
 CF the interweb TODO
 
+## Run it
+```
+docker run --name pythonsandbox --rm --network-mode host -v ./production_eleves:/app/python_app/modules -v ./data:/app/data adrianamaglio/pythonsandbox
+```
+(Logs will flow in your terminal, CTRL+C will stop the process).
+
+## Initialize it
+The directory `data` must contain a `users.txt` containing one username per line, or a `passwords.txt` file, containing `username=password` lines.  
+If you do not provide a password file, it will be generated from user file.  
+The password file is the database from which users/passwords are created in the system.  
+Additionnaly, you can add a file named `./data/init.sh` which will be executed before starting the servers. It is usefull for debuging or customisation purposes!
+
+## Use it
+You can now ssh into your localhost (and others computer on the same network can ssh into your host).
+Usernames and passwords are the one provided in the password file.  
+Students home directories are then listed in the `production_eleves` directory.
+
+# The docker image
 ## Build the docker image
 ```
-docker build . -t pythonsandbox
+docker build . -t adrianamaglio/pythonsandbox
 ```
 or pull it
 ```
@@ -49,12 +45,23 @@ And with user list file
 docker run -it --network host --name pythonsandbox -v "$(pwd)"/app/modules:/usr/share/app/modules -v "$(pwd)"/app/users.txt:/usr/share/app/users.txt pythonsandbox
 ```
 
-## Roadmap
+# How does it works?
+
+## A python script
+It run with uwsgi (CF dockerfile CMD line) and load python modules files according to URL.
+For instance, when you get `/test/my_function` the function `my_function` is executed from the file `test.py`.  
+Default behavior:
+- if `test` is a directory, we will try to load default function `index` from file `test/my_function.py`
+- if `test/my_function` is a directory, we will try to load default function `index` from file `test/my_function/main.py`
+GET arguments (the ones in URL), are passed as function parameter (only if the parameters name matches the arguments name).
+
+## SSH server
+Allow student to connect via SSH or SFTP to add python files and play with bash.
+
+## A docker image
+To bundle everything in one place.
+This docker image is not a pretty one, we should split those services into several containers.
+But that would be harder to run, so forget that.  
+Also, as this is poorly tested, the docker system make sure the environment is stable.
 
 
-## Example
-With the files under `./app/modules` you can get the following URLs :
-- http://localhost/mod1/func1_1
-- http://localhost/mod1/func1_2
-- http://localhost/myriem/mod2/func2_1
-