prod doc

Gemfile.lock

@@ -10,8 +10,7 @@ GEM
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.0)
     forwardable-extended (2.6.0)
     google-protobuf (4.28.2-arm64-darwin)
       bigdecimal
@@ -70,10 +69,9 @@ GEM
     rexml (3.3.8)
     rouge (4.4.0)
     safe_yaml (1.0.5)
-    sass-embedded (1.79.4-arm64-darwin)
-      google-protobuf (~> 4.27)
-    sass-embedded (1.79.4-x86_64-linux-gnu)
-      google-protobuf (~> 4.27)
+    sass-embedded (1.81.0)
+      google-protobuf (~> 4.28)
+      rake (>= 13)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.6.0)

README.md

@@ -1,6 +1,6 @@
-# Documentation template for OS2 projects
+# FleetOptimiser OS2 Documentation
 
-## 🏗️ Getting started 
+## ️ Getting started 
 
 This is a *bare-minimum* template to create a [Jekyll][Jekyll] site that:
 

_config.yml

@@ -1,8 +1,10 @@
-title: Just the Docs Template
-description: A starter template for a Jeykll site using the Just the Docs theme!
+title: FleetOptimiser OS2 Documentation
+description: The documentation of FleetOptimiser OS2
 theme: just-the-docs
 
 url: https://just-the-docs.github.io
 
+logo: /assets/fologos.png
+
 aux_links:
-  Template Repository: https://github.com/just-the-docs/just-the-docs-template
+  FleetOptimiser OS2: https://github.com/OS2fleetoptimiser/OS2fleetoptimiser

developing.md

@@ -0,0 +1,6 @@
+---
+title: Developing
+layout: default
+nav_order: 3
+---
+# Developing

extractors.md

@@ -0,0 +1,7 @@
+---
+title: Extractors
+layout: default
+nav_order: 4
+---
+
+# Extractors

index.md

@@ -1,35 +1,24 @@
 ---
 title: Home
 layout: home
+nav_order: 1
 ---
 
-This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details.
+# FleetOpimiser OS2 Documentation
 
-If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages.
+Welcome to the main documentation repo of FleetOptimiser OS2. The most important stuff in order to get up and running will be explained here.
+There are two main ways of running FleetOptimiser; as development with one or more services running as containers or as production where all services will be containerised.
 
-More specifically, the created site:
+### Production
+How to run FleetOptimiser in production will be explained on this dedicated [Production] page.
 
-- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem
-- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages
+### Developing
+Running FleetOptimiser in developer mode is easy and can be done in multiple ways. The most common will be explained on the [Developing] page.
 
-Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
+### Extractors
+In addition to the description of how to run FleetOptimiser, we also offer extraction modules to fleet management systems that loads and aggregate driving-data. 
+For more details go the [Extractors] page.
 
-[Browse our documentation][Just the Docs] to learn more about how to use this theme.
-
-To get started with creating a site, simply:
-
-1. click "[use this template]" to create a GitHub repository
-2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
-
-If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README.
-
-----
-
-[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
-
-[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
-[GitHub Pages]: https://docs.github.com/en/pages
-[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md
-[Jekyll]: https://jekyllrb.com
-[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
-[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
+[Extractors]: extractors.md
+[Production]: production.md
+[Developing]: developing.md

production.md

@@ -0,0 +1,89 @@
+---
+title: Production
+layout: default
+nav_order: 2
+---
+# Production
+Below you can see the complete production setup for FleetOptimiser. If running in production mode, it's required that users are validated through Keycloak.
+The users' type of access can be controlled through attributes on the identity provider or wide access can be given if environment variables are not provided.
+Webproxy is optional, but if used, proxy set headers must be forwarded. 
+
+
+![Production environment](/assets/foprod.png)
+
+
+
+### Prerequisites 
+- Environment capable of running docker and compose
+- Keycloak, a FleetOptimiser realm and client
+- Access to a database or mapping to a volume containing a db file
+
+### Images 
+We need the following images in order to run FleetOptimiser 
+- fleetoptimiser-frontend:latest
+- fleetoptimiser-backend:latest
+- rabbitmq:3-management
+- redis:latest
+
+### Setup
+As the production environment suggests, we need to make sure that the frontend and backend are on the same docker network.
+We do this to allow communication between the two, but from the outside, clients are only able to reach through the frontend.
+Hence, we don't need any authentication on the backend when we make the frontend middelware assert validity of the connection.
+
+The backend, worker and queue management share network in order to direct the processing and be able to handle multiple tasks 
+in the same environment. The worker and backend are on the same queue, so when a job is received it's queued to the right worker.
+
+The _docker-compose.yaml_ is dependent on a _.prod-env_ file that expects the following variables:
+
+| env                         | description                                                                                                                                      |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| CELERY_BACKEND_URL          | the uri to the running redis                                                                                                                     |
+| CELERY_BROKER_URL           | the uri to the running rabbitmq                                                                                                                  |
+| CELERY_QUEUE                | a unique name for the queue to use                                                                                                               |
+| RABBITMQ_DEFAULT_USER       | a username used to login to service                                                                                                              |
+| RABBITMQ_DEFAULT_PASS       | a password used to login to service                                                                                                              |
+| DB_NAME (optional)          | name of the database                                                                                                                             |
+| DB_USER (optional)          | user of the database                                                                                                                             |
+| DB_PASSWORD (optional)      | password of the user on the database                                                                                                             |
+| DB_URL (optional)           | host and port to the database                                                                                                                    |
+| DB_SERVER (optional)        | dialect and driver                                                                                                                               |
+| EXTRACTORS (optional)       | extractor to use when testing location precision. Comma separated list. Options; SKYHOST, MILEAGEBOOK, GAMFLEET, FLEETCOMPLETE, PUMA, SKYHOST_V2 |
+| {EXTRACTOR}_KEYS (optional) | list of keys to use with EXTRACTORS                                                                                                              |
+| TRIP_DURATION (optional)    | maximum number of days for a roundtrip                                                                                                           |  
+
+
+In addition to the above backend environments. The following environment variables are typed directly in the _docker-compose.yaml_ file for the frontend. 
+
+
+| env             | description                                                                                      |
+|-----------------|--------------------------------------------------------------------------------------------------|
+| KEYCLOAK_ID     | id of the keycloak registration                                                                  |
+| KEYCLOAK_SECRET | secret of the keycloak client registration                                                       |
+| KEYCLOAK_ISSUER | the realm authenticator of the keycloak provider                                                 |
+| NEXTAUTH_SECRET | a secret for the frontend to validate authentication                                             |
+| NEXTAUTH_URL    | host of the running application                                                                  |
+| ROLE_CHECK      | the matching role from the authentication if the user has access, if present user must have this |
+| ROLE_CHECK_READ | the matching role if user only has read access                                                   |
+
+
+#### Database
+DB environment variables are optional, since a dummy sqlite in memory DB will be loaded if nothing is provided.
+When a connection to database is established the tables and necessary settings data will be created. 
+
+#### Extractors
+The extractor specific env variables are used to feed in fleet provider specific details (api keys etc.), in order to do _live_ testing of aggregation precision.
+If not provided, the feature of testing precision when changing/adding parking spots will not work. Precision testing works with fleet management systems that does not require read entries to be patched. 
+
+### Running FleetOptimiser
+Run the queue services by running the following command
+```
+docker-compose -f redis-rabbit-docker-compose.yaml up
+```
+
+Run FleetOptimiser with frontend, backend api and a celery worker by running the following commnad
+```
+docker-compose -f docker-compose.yaml up
+```
+
+Now, FleetOptimiser can be accessed at the mapped port (localhost:8001).
+