Skip to content

Commit d0b376d

Browse files
stefanogermanostefanogermano
authored
Merge pull request #33 from DeMaCS-UNICAL/hotfix/updating-readme
Updating readme
2 parents d151d33 + 645596e commit d0b376d

File tree

1 file changed

+156
-4
lines changed

1 file changed

+156
-4
lines changed

Diff for: ‎README.md

+156-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,163 @@
1+
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/DeMaCS-UNICAL/LoIDE-API-Server/master/LICENSE)
2+
[![GitHub release](https://img.shields.io/github/release/DeMaCS-UNICAL/LoIDE-API-Server.svg)](https://github.com/DeMaCS-UNICAL/LoIDE-API-Server/releases/latest)
3+
[![GitHub issues](https://img.shields.io/github/issues/DeMaCS-UNICAL/LoIDE-API-Server.svg)](https://github.com/DeMaCS-UNICAL/LoIDE-API-Server/issues)
4+
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/DeMaCS-UNICAL/LoIDE-API-Server)
5+
16
# LoIDE-API-Server
7+
An API server for LoIDE clients.
8+
This component acts as an intermediary between LoIDE clients and server-side executors. It handles incoming requests from clients, forwards them to the appropriate executors, and then send the responses back to the clients.
9+
10+
# Getting Started
11+
12+
These instructions will get you a copy of the project up and running on your local machine.
13+
14+
## Prerequisites
15+
16+
To run LoIDE API Server you need to have Node.js and npm installed on your system. You can download and install Node.js from the [official website](https://nodejs.org/).
17+
18+
If you want to use the server-side features of LoIDE, you need to have a server that can execute Logic programs. If you like it, you can use our [PythonESE](https://github.com/DeMaCS-UNICAL/PythonESE).
19+
20+
## Installation
21+
22+
To install LoIDE API Server, first clone the repository using the following command:
223

3-
An API server for LoIDE clients
24+
```bash
25+
git clone https://github.com/DeMaCS-UNICAL/LoIDE-API-Server.git
26+
```
427

5-
## Available Scripts
28+
Navigate to the cloned repository directory and install the required dependencies with npm:
29+
30+
```bash
31+
npm install
32+
```
33+
34+
Now you can run the application in development or production mode.
35+
36+
## Run the Application
637

738
In the project directory, you can run:
839

9-
### `npm start`
40+
```bash
41+
npm start
42+
```
43+
44+
This will start the server and it will be immediately ready to receive requests.
45+
46+
# Dockerization
47+
48+
This repository provides also Docker containerization for LoIDE API Server.
49+
Docker enables the encapsulation of the LoIDE API Module within a lightweight, portable container, ensuring smooth deployment across various environments.
50+
51+
## Getting Started
52+
53+
Deploying the LoIDE API Server using Docker is straightforward:
54+
55+
### Installation
56+
57+
Ensure Docker is installed on your system (refer to the [official Docker documentation](https://docs.docker.com/get-docker/) for installation instructions). Then, clone this repository using the following command:
58+
59+
```bash
60+
git clone https://github.com/DeMaCS-UNICAL/LoIDE-API-Server.git
61+
```
62+
63+
### Building the Docker Image
64+
65+
A Docker image is a package that contains all the necessary to run application and it's used to create Docker containers. To create one navigate to the cloned repository directory and build the Docker image using the provided Dockerfile:
66+
67+
```bash
68+
docker build -t loide-api .
69+
```
70+
71+
### Running the Docker Container
72+
73+
Once the Docker image is built, you can run a Docker container using the following command:
74+
75+
```bash
76+
docker run -d --network host --mount type=bind,source=[your/path/to/config],target=/app/config loide-api
77+
```
78+
79+
The `--network host` option in the docker run command tells Docker to use the host network for the container. This means the container shares the same network stack as the host and can access network services running on the host directly.
80+
81+
The `--mount type=bind, source=[your/path/to/config], target=/app/config` option is used to create a bind mount. A bind mount is a type of mount that allows you to map a host file or directory to a container file or directory (for more information refer to the [official Docker documentation](https://docs.docker.com/storage/bind-mounts/)).
82+
In this case we use mounts to provide the configuration file to the container.
83+
84+
The configuration files are JSON files containing the configuration of the LoIDE API Server. They must be placed in a directory on the host and the _full_ path to this directory must be specified in the source option of the --mount option. The JSON schemas needs also to be in the same directory.
85+
86+
For examples on how to create or modify the configuration file refer to the next section. If no configuration file is provided the default configuration will be used.
87+
88+
89+
# Configuration
90+
91+
## app-config.json
92+
This configuration file is used to set up the server ports and SSL certificate paths for the application.
93+
94+
### Port
95+
96+
This property is an object that specifies the ports for the HTTP and HTTPS servers.
97+
98+
### Path
99+
100+
This property is an object that specifies the paths to the SSL certificate and key for the HTTPS server.
101+
102+
- `key`: The path to the SSL key file. Here, it's not provided, which means the HTTPS server will not be started.
103+
- `cert`: The path to the SSL certificate file. Similarly, it's not provided here, so the HTTPS server will not be started.
104+
105+
## services.json
106+
This configuration file is used to define the programming languages, solvers, executors, and options supported by the application.
107+
108+
### Structure
109+
110+
The configuration file is structured as a JSON object with a single property: `languages`. This property is an array where each object represents a programming language.
111+
112+
### Languages
113+
114+
Each language object has three properties:
115+
116+
- `name` is the display name of the language.
117+
- `value` is the value that represents the language.
118+
- `solvers` is an array of solver objects that are supported by the language.
119+
120+
### Solvers
121+
122+
Each solver object within a language has four properties:
123+
124+
- `name` is the display name of the solver.
125+
- `value` is the value that represents the solver.
126+
- `executors` is an array of executor objects that are supported by the solver.
127+
- `options` is an array of option objects that are supported by the solver.
128+
129+
### Executors
130+
131+
Each executor object within a solver has six properties:
132+
133+
- `protocol` is the protocol used by the executor (e.g., "ws" for WebSocket).
134+
- `url` is the URL of the executor.
135+
- `name` is the display name of the executor.
136+
- `value` is the value that represents the executor.
137+
- `path` is the path on the executor's server.
138+
- `port` is the port on which the executor's server is listening.
139+
140+
### Options
141+
142+
Each option object within a solver has four properties:
143+
144+
- `name` is the display name of the option.
145+
- `value` is the value that represents the option.
146+
- `word_argument` is a boolean indicating whether the option requires an argument.
147+
- `description` is a description of the option.
148+
149+
## Versioning
150+
151+
We use [Semantic Versioning](http://semver.org) for versioning. For the versions available, see the [releases on this repository](https://github.com/DeMaCS-UNICAL/LoIDE-API-Server/releases).
152+
153+
## Credits
154+
155+
- Stefano Germano (_Coordinator_)
156+
- Rocco Palermiti
157+
- Marco Duca
158+
159+
From the [Department of Mathematics and Computer Science](https://www.mat.unical.it) of the [University of Calabria](http://unical.it)
160+
161+
## License
10162

11-
Run the LoIDE Web Server.
163+
This project is licensed under the [MIT License](LICENSE)

0 commit comments

Comments
 (0)