Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[enhancement/readme] Improved readme #48

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

[enhancement/readme] Improved readme #48

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3fcebb5
[enhancement/readme] Improved readme
Alathreon Aug 1, 2024
a004e01
Added diagram in README.md
Alathreon Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 38 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,39 @@
## Prerequisites
- Java 21
- Docker
## Used technologies
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Rename to "Technology Stack".
  • Merge this section with Prerequisites section;
  • Add a note in which you inform that Docker is mandatory.
  • Add version number of each technology used.

Technologies used in this project, and so technologies that you should know before contributing.
- Java
- Spring
- Gradle
- Docker (knowing Docker is the most important thing in this project)

# Structure of the project
There are two projects, JShellAPI and JShellWrapper
JShellAPI is a REST API, and whenever some code is received, it will create a session, by creating a docker container, which will run JShellWrapper inside and then execute the given code in JShellWrapper.
There are two projects, JShellAPI and JShellWrapper.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • It would be nice to make JShellAPI and JShellWrapper words as links.
  • it's better to say This project is composed of 2 sub-projects, both are Backend services (as indicated in the name of the repo)
  • I highly suggest to share the source of the diagram so we can update anytime we want.


JShellAPI is a REST API, where whenever some code is received, it will create a session, by creating a docker container, which will run JShellWrapper inside and then execute the given code.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Add a title here to inform that this section is about the 1st sub-project;
  • Bring any relevant information to JShellApi project under this section;
  • It would be better to make REST API keyword as a link to Restful API website;
  • We need to explain to explain that REST API (JShellApi) is the entry point to JShellWrapper and not the opposite.
  • We need to explain why we don't allow executing the code within the REST API service (reasons or links);


![JShellAPI diagram](https://github.com/user-attachments/assets/c566b8c0-cf81-4a56-8a0a-5715c33105a7)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Why not putting the diagram img within the repo ?
  • There is no mention of a scenario for using an existing session;
  • Why there is no mention to session on the diagram?


There are three unrelated ways to run JShellPlaygroundBackend:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it would be better to say There are 3 ...

- [JShellWrapper alone](#how-to-use-jshellwrapper-alone-in-local) in case you specifically want to improve or debug the wrapper
- [JShellAPI in local](#how-to-use-jshellapi) in case you specifically want to improve or debug the API
- [JShellAPI in docker](#how-to-build-jshellapi-and-run-it-in-docker) in case you want to run it like it is used in production, which can be important, because the API needs to create containers from docker inside itself

## How to use JShellWrapper alone in local
This is only useful if your intent is to run the wrapper alone, without the API, for example if you want to improve the wrapper or debug it.
### From console
* Set the environment variable `evalTimeoutSeconds=15` and `sysOutCharLimit=1024`
* * On `Windows CMD`, use `set evalTimeoutSeconds=15 && set sysOutCharLimit=1024`
* * On `Windows Powershell`, use `$env:evalTimeoutSeconds=15 && $env:sysOutCharLimit=1024`
* * On `Linux Shell`, use `export evalTimeoutSeconds=15 && export sysOutCharLimit=1024`
* Run `./gradlew JShellWrapper:run`
* Alternatively, run:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest to delete this part :

* Set the environment variable `evalTimeoutSeconds=15` and `sysOutCharLimit=1024`
* * On `Windows CMD`, use `set evalTimeoutSeconds=15 && set sysOutCharLimit=1024`
* * On `Windows Powershell`, use `$env:evalTimeoutSeconds=15 && $env:sysOutCharLimit=1024`
* * On `Linux Shell`, use `export evalTimeoutSeconds=15 && export sysOutCharLimit=1024`
* Run `./gradlew JShellWrapper:run`
* Alternatively, run:

* * On `Windows CMD`, `set evalTimeoutSeconds=15 && set sysOutCharLimit=1024 gradlew JShellWrapper:run`
* * On `Windows Powershell`, `$env:evalTimeoutSeconds=15 && $env:sysOutCharLimit=1024 ./gradlew JShellWrapper:run`
* * On `Linux Shell`, `evalTimeoutSeconds=15 sysOutCharLimit=1024 ./gradlew JShellWrapper:run`
### From IntelliJ
- Go in Run → Run... → Edit Configurations → create a configuration
- Go in Run → Run... → Edit Configurations → create a gradle configuration
- Select the command `JShellWrapper:run`
- Click on modify options, and check `VM options`
- Then add `evalTimeoutSeconds=15;sysOutCharLimit=1024` in the VM options
Expand All @@ -26,9 +51,9 @@ JShellAPI is a REST API, and whenever some code is received, it will create a se
- Run `JShellWrapper:jibDockerBuild` to build the image
- Run `bootRun`

# How to build JShellAPI in and run it in Docker
# How to build JShellAPI and run it in Docker
- Launch Docker
- Run `jibDockerBuild` to create the image
- Run `./gradlew jibDockerBuild` to create the image
- Create a folder outside the project
- `cd` to this folder
- Copy `docker-compose.yaml` inside it
Expand All @@ -45,5 +70,12 @@ JShellAPI is a REST API, and whenever some code is received, it will create a se
-application.yaml
```

## How to use JShellApi ?
### Try JShell API
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Place this section under JShellApi section

Create a session called `test` and execute `2+2` on it.
Note that the port might be different.
```shell
curl --request POST --url http://localhost:8080/jshell/eval/test --data '2+2'
```

### How to use JShellApi ?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please place this under a JShellAPi section

See [JShellAPI README](JShellAPI/README.MD)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be better to bring the content here and add note to inform that it's NOT updated

Loading