Web app installation and usage

Internal-architecture-(original).md

@@ -1,59 +0,0 @@
-## File Server
-
-**File Server** stores data, that should be kept outside of **WebApp's** 
-database (both because storing files in a database is inefficient and because 
-the workers need to access the files in the simplest possible way). It should 
-meet following requirements:
-- store files without duplicates
-- keep consistent state with main database
-- serve files to workers on demand
-- allow versioning of tasks with revert back feature
-
-To meet these requirements, **Storage** and **Database** must be set as bellow.
-
-### Storage
-**Storage** is meant as disc space with some commonly used filesystem. We'll use `ext4`, but the other ones should work too. **Storage** file structure is:
-```
-.
-├── submits
-│   └── user_id
-│       └── advanced_dot_net_1
-│           └── submit_id
-│               ├── eval.yml
-│               └── source.cs
-├── submit_archives
-│   └── submit_id.tar.gz
-├── tasks
-│   ├── a
-│   │   ├── a014ed2abb56371bfaf2b4298a85d5dfb56509ed
-│   │   └── a5edbd8b12e670ed1e3110d6c0524000cd4c3c7a
-│   └── b
-│       └── b1696358b8540923eb79b68f95c0f94c13a83fa7
-└── temp
-    └── 1795184136b8bdddabe50453cc2cc2d46f0f7c5e
-```
-- **submits** keep information about all files submited by users to ReCodEx. 
-  There are subdirectories _user_id_ and _advanced_dot_net_1_ which groups
-  submits by users and courses the submits are for. This structure is easy to 
-  maintain for new and deleted users.
-- **submit_archives** contains the student submissions in compressed archives so 
-  that they can be easily downloaded by workers.
-- **tasks** contains supplementary files (such as test inputs or helper 
-  programs) for all existing task in ReCodEx. To avoid too many files in one 
-  directory, files are separated to subfolders by first character of their name.
-- **temp** directory is dedicated to temporary storing outputs of programs on teachers' demand. This directory will be erased by cron job on daily basis.
-
-### Database
-For user friendly access and modifying tasks following information should be stored in database:
-- list of tasks with their newest version number
-- for every task and version list of used files (their hashed names)
-- for every hash name one human readable filename
-
-### Conclusion
-Files are internally stored by their `sha1sum` hashes, so it's easy to implement 
-versioning and get rid of files with duplicate content (multiple files can have 
-the same content, which is only stored once). **Worker** also uses files by 
-their hashes, which is great for local caching without worries about actual 
-version number of given file. On the other hand, **Database** stores information 
-about human readable names, so that the files are presented in a friendly way to 
-users (teachers) in **WebApp**.

Web-application.md

@@ -52,6 +52,62 @@ There are two basic types of React components - presentational and stateful comp
 
 *Redux* simplifies this architecture by allowing only a single *store* and introducing a special pure function called *reducer* which deterministically transforms *old* state to a *new* state according to the given *action*. The *state* of app is represented by one plain javascript object - a tree - inside the *store*. *Reducer* is commonly a function composed by many simple functions which handle only a small subtree of the whole state.
 
+
 ## Installation
 
-## Configuration and usage
+Web application requires NodeJS server as its runtime environment. Stable versions of 4th and 6th series are sufficient, using at least 6th series is highly recommended. Please check version of NodeJS in your distribution's repositories, there is often too old one. However there are some third party repositories for all main linux systems.
+
+The app depends on several libraries and components, all of them are listed in `package.json` file in source repository. For managing dependencies is used node package manager (`npm`), which can come with NodeJS installation otherwise can be installed separately. To fetch and install all dependencies run:
+```
+$ npm install
+```
+
+To easy production usage there is additional package for managing NodeJS processes, `pm2`. This tool can run your application as a daemon, monitor occupied resources, gather logs and provide simple console interface for managing app's state. To install it globally into your system run:
+```
+# npm install pm2 -g
+```
+
+For production it's also recommended to use full fledged web server like Apache or Nginx as a proxy providing HTTPS encryption and caching of static files.
+
+
+## Configuration and usage
+
+The application can be run in two modes, development and production.
+
+- Development mode can be use for local testing of the app. This mode uses webpack dev server, so all code runs on a client, there is no server side rendering available. Starting is simple command, default address is http://localhost:8080.
+```
+$ npm run dev
+```
+- Production mode us mostly used on the servers. It provides all features such as server side rendering. This can be run via:
+```
+$ npm run build
+$ npm run start
+```
+
+Both modes can be configured to use different ports or set base address of used API server. This can be configured in `.env` file in root of the repository. There is `.env-sample` file which can be just copied and altered.
+
+The production mode can be run also as a demon controled by `pm2` tool. First the web application has to be built and then the server javascript file can run as a daemon.
+```
+$ npm run build
+$ pm2 start bin/server.js
+```
+
+The `pm2` tool has several options, most notably _status_, _stop_, _restart_ and _logs_. Further description is available on project [website](http://pm2.keymetrics.io).
+
+#### Configurable items
+
+Description of configurable options. Bold are required values, optional ones are in italics.
+
+- **NODE_ENV** -- mode of the server
+- **API_BASE** -- base address of API server, including port and API version
+- **PORT** -- port where the app is listening
+- _WEBPACK_DEV_SERVER_PORT_ -- port for webpack dev server when running in development mode. Default one is 8081, this option might be useful when this port is necessary for some other service.
+
+#### Example configuration file
+```
+NODE_ENV=production
+API_BASE=https://recodex.projekty.ms.mff.cuni.cz:4000/v1
+PORT=8080
+# WEBPACK_DEV_SERVER_PORT=8081
+```
+