Add mkdocs site

Author: santiagolizardo

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: ci 
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force
+

.gitignore

@@ -0,0 +1 @@
+site/

Makefile

@@ -0,0 +1,13 @@
+
+.PHONY: docs-serve
+docs-serve: deps-install
+	mkdocs serve
+
+.PHONY: deps-install
+deps-install:
+	pip install -r requirements.txt
+
+.PHONY: docs-build
+docs-build:
+	mkdocs build
+

README.md

@@ -0,0 +1,16 @@
+# Reconmap documentation
+
+This repository contain the markdown files that generate content for https://reconmap.com
+
+## Dependencies
+
+- Python
+- PIP
+- Make
+
+## How to run locally
+
+```shell
+make
+xdg-open http://localhost:8000
+```

docs/CNAME

@@ -0,0 +1 @@
+reconmap.com

docs/admin-manual/attachment-limits.md

@@ -0,0 +1,11 @@
+---
+title: Attachment limits
+parent: Admin manual
+---
+
+The docker images provided by Reconmap come with some pre-defined limits that we consider reasonable for most of the use cases we have encounter. Some of the limits can be found below:
+
+| File           | Max upload size |
+| -------------- | --------------- |
+| Attachment     | 20MB            |
+| Command output | 10MB            |

docs/admin-manual/configuring-cors.md

@@ -0,0 +1,31 @@
+---
+title: Configuring CORS
+parent: Admin manual
+---
+
+The Cross-Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) settings can be found in the `config.json` file in the API backend directory. If the file does not exist, create one using [this template file](https://github.com/reconmap/rest-api/blob/master/config-template.json) as a template.
+
+Edit the content of the file to show (adjusting the values accordingly):
+
+### Allowing any domain from a list
+
+```json
+{
+  "cors": {
+    "allowedOrigins": ["http://localhost:5500", "http://127.0.0.1:5500"]
+  }
+}
+```
+
+### Allowing any origin
+
+**CAUTION:** This configuration is not recommended as it relaxes the security rules for your instance, but it can be handy for debugging purposes.
+{: .fw-700 .p-2 .text-red-200 .bg-yellow-100 }
+
+```json
+{
+  "cors": {
+    "allowedOrigins": ["*"]
+  }
+}
+```

docs/admin-manual/configuring-database-settings.md

@@ -0,0 +1,19 @@
+---
+title: Configuring database settings
+parent: Admin manual
+---
+
+The database settings can be found in the `config.json` file in the API backend directory. If the file does not exist, create one using [this file](https://github.com/Reconmap/api-backend/blob/master/config-template.json) as a template.
+
+Edit the content of the file to show (adjusting the values accordingly):
+
+```json
+{
+  "database": {
+    "host": "rmap-mysql",
+    "username": "reconmapper",
+    "password": "reconmapped",
+    "name": "reconmap"
+  }
+}
+```

docs/admin-manual/configuring-logging-settings.md

@@ -0,0 +1,103 @@
+---
+title: Configuring logging settings
+parent: Admin manual
+---
+
+Reconmap API can be configured to log application messages to multiple destinations including local files or remote sys log servers.
+
+### Logging to local files
+
+Edit the `config.json` to show the following content at the top level:
+
+```json
+{
+  ...
+  "logging": {
+    "file": {
+      "enabled": true,
+      "level": "debug",
+      "path": "/var/www/webapp/logs/application.log"
+    }
+  },
+  ...
+}
+```
+
+### Logging to Graylog using GELF
+
+First make sure to spin up a [Graylog](https://www.graylog.org/) somewhere in your system. You can use the following docker compose file to start one with all its dependencies.
+
+```yaml
+version: "3.8"
+
+services:
+  elasticsearch:
+    image: "docker.elastic.co/elasticsearch/elasticsearch:7.12.1"
+    environment:
+      - node.name=elasticsearch
+      - cluster.name=docker-cluster
+      - bootstrap.memory_lock=true
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+    volumes:
+      - esdata:/usr/share/elasticsearch/data
+    ports:
+      - 9200:9200
+  mongodb:
+    image: "mongo:4.2"
+    restart: always
+
+  graylog:
+    image: "graylog/graylog:4.3.2"
+    depends_on:
+      - elasticsearch
+      - mongodb
+    entrypoint: "/usr/bin/tini -- wait-for-it elasticsearch:9200 --  /docker-entrypoint.sh"
+    environment:
+      GRAYLOG_PASSWORD_SECRET: somepasswordpepper
+      # to generate a password hash, type: echo -n admin | shasum -a 256
+      GRAYLOG_ROOT_PASSWORD_SHA2: 8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918
+      GRAYLOG_HTTP_BIND_ADDRESS: "0.0.0.0:9001"
+      GRAYLOG_HTTP_EXTERNAL_URI: "http://localhost:9001/"
+      GRAYLOG_ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
+      GRAYLOG_MONGODB_URI: "mongodb://mongodb:27017/graylog"
+    ports:
+      - "5044:5044/tcp" # Beats
+      - "5140:5140/udp" # Syslog
+      - "5140:5140/tcp" # Syslog
+      - "5555:5555/tcp" # RAW TCP
+      - "5555:5555/udp" # RAW TCP
+      - "9001:9001/tcp" # Server API
+      - "12201:12201/tcp" # GELF TCP
+      - "12201:12201/udp" # GELF UDP
+      - "13301:13301/tcp" # Forwarder data
+      - "13302:13302/tcp" # Forwarder config
+volumes:
+  esdata:
+```
+
+Ensure to edit `config.json` file to enable the gelf log handler and point to the hostname and IP of your graylog server.
+
+```json
+{
+  ...
+  "logging": {
+    "gelf": {
+      "enabled": true,
+      "level": "debug",
+      "serverName": "api-graylog-1",
+      "serverPort": 12201
+    }
+  },
+  ...
+}
+```
+
+Now you can view all your application logs from the convenience of your browser at [http://localhost:9001](http://localhost:9001)
+
+![Graylog log management](/images/integrations/graylog.png)

docs/admin-manual/configuring-smtp-settings.md

@@ -0,0 +1,21 @@
+---
+title: Configuring SMTP settings
+parent: Admin manual
+---
+
+The SMTP settings can be found in the `config.json` file in the API backend directory. If the file does not exist, create one using [this file](https://github.com/Reconmap/api-backend/blob/master/config-template.json) as a template.
+
+Edit the content of the file to show (adjusting the values accordingly):
+
+```json
+{
+  "smtp": {
+    "host": "just.another.smtp.server",
+    "port": 587,
+    "username": "smtpuser",
+    "password": "smtpsecret",
+    "fromEmail": "no-reply@reconmap.com",
+    "fromName": "Reconmap"
+  }
+}
+```