Finalise project state

- Update Java docs
- Update readme

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Change Log
 
+# [0.4.0](CHANGEME) (2020.03.30)
+
+### Features
+
+* Updated documentation
+* Updated readme
+
+### Future features
+
+* Improve logging (container stats to CSV)
+* Add SLOC and execution time in response JSON
+* Attempt to improve polling performance/refactor code
+
+### Done
+
+* Tested all endpoints and fixed most of the bugs
+
 # [0.3.0](35842fe3e47c04ab715dbb2dac0e96622e0c38d1) (2020.03.30)
 
 ### Features

CONTRIBUTING.md

@@ -1,9 +1,5 @@
 # Contribution Guidelines
 
-I expect to put this on pypi soon, so when that's done
-installation will be a case of `python3 -m pip install code-ingest`
-For now though:
-
 Start by installing pyenv and poetry.
 
 Then clone the repo and change into the relevant directory.
@@ -14,6 +10,8 @@ Run the virtualenv: `poetry shell`
 
 From there, to deploy this app, just type `ingest_server`
 
+Further documentation can be found in the [docs](docs/ingest.rst)
+
 Feel free to suggest code changes.
 All code is formatted and tested to be compliant with `flake8`.
 Mypy compliance is also followed, just run `mypy` in the repo.

README.md

@@ -2,5 +2,69 @@
 
 This is the code ingest and execution server for RACTF.
 
-This runs code in a time-limited, offline docker container,
-and returns the results.
+This runs code in a time-limited, offline docker container and returns the results.
+
+It's written to meet a specific set of requirements and work in conjunction with a webapp front end.
+
+## Prerequsites & Setup
+
+- python 3.7 or above with pip
+- pyenv installed (optional)
+- poetry installed
+
+If you don't have the required python version, install [pyenv](https://github.com/pyenv/pyenv#basic-github-checkout) with basic checkout.
+Then install the build dependencies, which is listed on the [wiki](https://github.com/pyenv/pyenv/wiki)
+
+Add the following lines to your `~/.bashrc` file (assuming you haven't done so from the pyenv guide):
+
+```bash
+# Pyenv installation
+
+if [[ -z "$VIRTUAL_ENV" ]]; then
+    export PATH="$HOME/.pyenv/bin:$PATH"
+    eval "$(pyenv init -)"
+fi
+```
+
+If you have a different shell, follow the pyenv install guide. Pyenv isn't mandatory. If you have `python 3.7` or above,
+you should be fine.
+
+Next, install [poetry](https://python-poetry.org/docs/) with their suggested way, as this is necessary for the installation.
+
+```bash
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
+```
+**Note**: Poetry requires python2, so make sure you have that installed.
+
+## Installation & Deployment
+
+Clone the repo and change directory into it:
+
+```bash
+git clone https://gitlab.com/ractf/code-ingest.git
+cd code-ingest
+
+# If you're deploying for production.
+poetry install --no-dev
+poetry shell
+
+# <Set your environment variables here>
+ingest_server
+
+# If you're interested in making changes.
+poetry install
+poetry shell
+python -m code_ingest
+```
+
+You should be able to use any virtualenv realistically.
+
+The full documentation of environment variables, endpoints, etc can be found in the [docs](docs/ingest.rst)
+
+## Issues
+
+If you encounter a bug, please create an issue stating with as much possible detail:
+
+- Your set-up
+- The bug
+- Any steps taken

docs/ingest.rst

@@ -26,8 +26,8 @@ It is assumed the environment variables supplied will be in the correct format.
 
 Under the :code:`tests/` directory, you can also find :code:`functionality_check.py` which can be used to test
 the server out in a hurry. It's poorly written but allows you to access the features. If you've
-installed this from pypi, just swap the filename with the :code:`ingest_tests` command, which should be
-available to you if pip has setup your :code:`PATH` correctly.
+installed this using poetry venv and you're in the :code:`poetry shell`, just swap the filename with the :code:`ingest_tests`
+command, which should be available to you if poetry has setup your :code:`PATH` correctly.
 
 Run a basic functionality test of all the endpoints:
 
@@ -185,6 +185,20 @@ The returned JSON will have a :code:`token` parameter with the container token.
 
 Runs java code with OpenJDK 11.0.5.
 
+**Java programs have to have files and classes named in a certain way!**
+
+The file name will be called :code:`program.java` and hence there needs to be a class
+in the submitted code called :code:`Program` with a :code:`main` method. This is essential
+or else the code will not run!
+
+Here's an example 'Hello, world!' program for demonstration:
+
+:code:`public class Program {public static void main(String[] args) {System.out.println("Hello, World!");}}`
+
+How this class is generated is up to the backend/frontend user, though I will suggest using a template with
+this class for the frontend where this code is automatically inserted when the user selects Java for the
+language to use.
+
 Success data:
 
 The returned JSON will have a :code:`token` parameter with the container token.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "code-ingest"
-version = "0.3.0"
+version = "0.4.0"
 description = "The sort of CI server you're happy to let people throw crap at!"
 authors = ["RACTF Contributors"]
 license = "AGPL-3.0-only"