diff --git a/.gitignore b/.gitignore
index 4288729ae58a97160692aba9d1b52be78c660e06..a07e4314dbc96e55df882e28e4bec0527465c4ee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -90,4 +90,5 @@ log/
target/
testdb/
tomcat.*/
-/jams
\ No newline at end of file
+/jams
+userguide/site
\ No newline at end of file
diff --git a/build-doc.sh b/build-doc.sh
new file mode 100755
index 0000000000000000000000000000000000000000..0aea5d169b7ecded14193390dd3f32bb7afd3048
--- /dev/null
+++ b/build-doc.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+mkdir -p jams
+cd userguide || exit
+mkdocs build
+cp site/pdf/combined.pdf ../jams/userguide.pdf
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index ceba8d1dab08b3b33827125648150b6e731a7f64..829d0821d9deeace000297f3cea325c761f82adc 100644
--- a/pom.xml
+++ b/pom.xml
@@ -57,6 +57,7 @@
<ez.vcard.version>0.10.6</ez.vcard.version>
<maven.resources.version>3.1.0</maven.resources.version>
<embedded.ldap.unit>0.8.1</embedded.ldap.unit>
+ <maven.exec.version>1.1.1</maven.exec.version>
</properties>
<dependencies>
@@ -142,6 +143,24 @@
</filesets>
</configuration>
</plugin>
+ <plugin>
+ <artifactId>exec-maven-plugin</artifactId>
+ <groupId>org.codehaus.mojo</groupId>
+ <version>${maven.exec.version}</version>
+ <inherited>false</inherited>
+ <executions>
+ <execution><!-- Run our version calculation script -->
+ <id>Build PDF Documentation</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>exec</goal>
+ </goals>
+ <configuration>
+ <executable>build-doc.sh</executable>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
</plugins>
</build>
diff --git a/userguide/docs/admin.md b/userguide/docs/admin.md
new file mode 100644
index 0000000000000000000000000000000000000000..689ca1721efdcba33966bdad8fbaebb8f7298420
--- /dev/null
+++ b/userguide/docs/admin.md
@@ -0,0 +1,88 @@
+# Admin Guide
+
+By default Jams runs an embedded tomcat server visible on port 8080, however this is not practical for many reasons. This guide is designed
+to help you setup Jams to run in a production environment.
+
+
+## Jams & Nginx
+
+It is generally not recommended to expose Jams directly to the outside world and while it is possible to run Jams in SSL mode, we usually
+recommend users to place it behind Nginx or a similar web server which proxies requests between the outside world and Jams.
+
+The following is an example map of how you could configure JAMS behind Nginx (the process would be similar if you wanted to use any other type of proxying solution):
+
+<p align="center">
+ <img src="../img/map.png" alt="Create an admin account" style="height:250px;width:600px"/>
+</p>
+
+The IP 10.10.0.1 is random, and should be seen as an example.
+
+
+Typically you would add a new site called ``jams-site.conf`` to your nginx configurations which would contain the following entries if you wanted to place an SSL certificate at the Nginx level:
+
+
+```
+server {
+ listen 443 ssl;
+ listen [::]:443 ssl;
+ ssl on;
+ ssl_certificate /etc/certificates/mycertificate.pem
+ ssl_certificate_key /etc/certificates/mycertificatekey.pem
+ client_max_body_size 100M;
+ server_name jams.mycompany.com;
+ location / {
+ proxy_pass http://10.10.0.1:8080/;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header Host $http_host;
+ }
+}
+```
+
+This is the preferred setup method by most admins, as local traffic is usually ran unencrypted since it is usually either inter-VM connection, a VLAN or another dedicated link.
+
+## Running Jams with SSL
+
+If necessary it is possible to run Jams with SSL. In this case, you need to overload the command-line arguments when starting the server.
+
+```java -jar jams-launcher.jar PORT SSL_CERTIFICATE SSL_CERTIFICATE_KEY```
+
+| Argument | Details |
+| ------------- |------------- |
+| **PORT** | The TCP port on which you want Jams to listen for incoming connections |
+| **SSL_CERTIFICATE** | The location of the PEM-formatted SSL Certificate file |
+| **SSL_CERTIFICATE_KEY** | The location of the PEM-formatted key file which is used with the SSL Certificate file from above |
+
+
+An example of the command would be: ```java -jar jams-launcher.jar 8443 /opt/mycert.pem /opt/mycertkey.pem```
+
+
+<span style="color:red">**Current Limitation Warning: Jams does not support reading encrypted private keys which require a password unlock.**</span>
+
+There are only two possible cases when you would want to run Jams with SSL - we do not recommend this method:
+
+1. Your local traffic is exposed to many actors (employees, contractors) and there is no possibility to isolate it
+2. You want to expose Jams directly to the external world because proxying is not an option
+
+
+## Running Jams as a Linux Service
+
+Running Jams as a Linux Service is fairly straightforward with systemd - you simply created a service unit file with the following structure:
+
+```
+[Unit]
+Description=JAMS Server
+
+[Service]
+Type=simple
+WorkingDirectory=[DIRECTORY WHERE JAMS WAS UNZIPPED]
+ExecStart=/usr/bin/java -jar [DIRECTORY WHERE JAMS WAS UNZIPPED]/jams-launcher.jar PORT SSL_CERTIFICATE SSL_CERTIFICATE_KEY
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The parameters PORT, SSL_CERTIFICATE and SSL_CERTIFICATE_KEY are optional (however, PORT can be used alone whereas the SSL_CERTIFICATE comes in pair with SSL_CERTIFICATE_KEY)
+
+## Running Jams as a Windows Service
+
+In progress.
\ No newline at end of file
diff --git a/userguide/docs/clients.md b/userguide/docs/clients.md
new file mode 100644
index 0000000000000000000000000000000000000000..e20f08d29c7892d530cb43fed02a38ae62de45b0
--- /dev/null
+++ b/userguide/docs/clients.md
@@ -0,0 +1,76 @@
+# Client Guide
+
+Depending on your operating system, we have included the tutorial on how to connect to the management server using the Windows, Android and Mac OS X clients.
+
+
+For the purposes of this tutorial, we assume that
+
+1. The server and the device trying to connect are either
+ 1. On the same network
+ 2. The server is publicly accessible to the outside world
+2. You have a valid username/password pair to connect to the server
+
+## Connecting using Android
+
+Upon opening Jami, you will be offered the following screen
+
+<p align="center">
+ <img src="../img/client/android/android-step1.jpg" alt="Step 1" style="height:400px;width:200px"/>
+</p>
+
+
+You should select the option **"CONNECT TO MANAGEMENT SERVER"** which will lead you to the following screen:
+
+
+<p align="center">
+ <img src="../img/client/android/android-step2.jpg" alt="Step 1" style="height:400px;width:200px"/>
+</p>
+
+The server in this case would be the DNS address of your server and the username and password which correspond to your account. If you have configured the server with an LDAP/AD backend, it would be your LDAP/AD username and password.
+
+## Connecting using Mac OS
+
+Upon opening Jami, you will be offered the following screen
+
+<p align="center">
+ <img src="../img/client/macos/macos-step1.png" alt="Step 1" style="height:400px;width:600px"/>
+</p>
+
+
+Click on **Advanced** and additional options will appear:
+
+<p align="center">
+ <img src="../img/client/macos/macos-step2.png" alt="Step 1" style="height:400px;width:600px"/>
+</p>
+
+You should select the option **"CONNECT TO MANAGEMENT SERVER"** which will lead you to the following screen:
+
+<p align="center">
+ <img src="../img/client/macos/macos-step3.png" alt="Step 1" style="height:400px;width:600px"/>
+</p>
+
+The ```Account manager``` in this case would be the DNS address of your server and the username and password which correspond to your account. If you have configured the server with an LDAP/AD backend, it would be your LDAP/AD username and password.
+
+## Connecting using Windows
+
+
+Upon opening Jami, you will be offered the following screen
+
+<p align="center">
+ <img src="../img/client/windows/windows-step0.png" alt="Step 1" style="height:400px;width:500px"/>
+</p>
+
+
+Click on **Advanced** and additional options will appear:
+
+<p align="center">
+ <img src="../img/client/windows/windows-step1.png" alt="Step 1" style="height:400px;width:500px"/>
+</p>
+
+You should select the option **"Connect to account manager"** which will lead you to the following screen:
+
+<p align="center">
+ <img src="../img/client/windows/windows-step3.png" alt="Step 1" style="height:400px;width:500px"/>
+</p>
+
+The ```Account manager``` in this case would be the DNS address of your server and the username and password which correspond to your account. If you have configured the server with an LDAP/AD backend, it would be your LDAP/AD username and password.
\ No newline at end of file
diff --git a/userguide/docs/img/ad.png b/userguide/docs/img/ad.png
new file mode 100644
index 0000000000000000000000000000000000000000..847482e6791c5b3e351a186cd918cff78bed7f67
Binary files /dev/null and b/userguide/docs/img/ad.png differ
diff --git a/userguide/docs/img/client/android/android-step1.jpg b/userguide/docs/img/client/android/android-step1.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..e691beb909f21928bb23e65a3dce8c8c841313fd
Binary files /dev/null and b/userguide/docs/img/client/android/android-step1.jpg differ
diff --git a/userguide/docs/img/client/android/android-step2.jpg b/userguide/docs/img/client/android/android-step2.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..f832ab782aa317c893cc78d777b39c3f7de4f9ac
Binary files /dev/null and b/userguide/docs/img/client/android/android-step2.jpg differ
diff --git a/userguide/docs/img/client/macos/macos-step1.png b/userguide/docs/img/client/macos/macos-step1.png
new file mode 100644
index 0000000000000000000000000000000000000000..3557d2aec2dcb284364464feb48e8ea09fe91ae3
Binary files /dev/null and b/userguide/docs/img/client/macos/macos-step1.png differ
diff --git a/userguide/docs/img/client/macos/macos-step2.png b/userguide/docs/img/client/macos/macos-step2.png
new file mode 100644
index 0000000000000000000000000000000000000000..1b970fa57fa8463486da62ca8026cc59f64cea0c
Binary files /dev/null and b/userguide/docs/img/client/macos/macos-step2.png differ
diff --git a/userguide/docs/img/client/macos/macos-step3.png b/userguide/docs/img/client/macos/macos-step3.png
new file mode 100644
index 0000000000000000000000000000000000000000..60d946946145b21d2cf48f1585f2f6b3a7d27bae
Binary files /dev/null and b/userguide/docs/img/client/macos/macos-step3.png differ
diff --git a/userguide/docs/img/client/windows/windows-step0.png b/userguide/docs/img/client/windows/windows-step0.png
new file mode 100644
index 0000000000000000000000000000000000000000..9374e6fe1de8816586b2135463859b1ce81a479a
Binary files /dev/null and b/userguide/docs/img/client/windows/windows-step0.png differ
diff --git a/userguide/docs/img/client/windows/windows-step1.png b/userguide/docs/img/client/windows/windows-step1.png
new file mode 100644
index 0000000000000000000000000000000000000000..273869c8dc9f80f6bea4c6c86c0d87d88e53601f
Binary files /dev/null and b/userguide/docs/img/client/windows/windows-step1.png differ
diff --git a/userguide/docs/img/client/windows/windows-step3.png b/userguide/docs/img/client/windows/windows-step3.png
new file mode 100644
index 0000000000000000000000000000000000000000..7482adf05665ba69a755a36824b0c96234c7d24b
Binary files /dev/null and b/userguide/docs/img/client/windows/windows-step3.png differ
diff --git a/userguide/docs/img/device_enroll.png b/userguide/docs/img/device_enroll.png
new file mode 100644
index 0000000000000000000000000000000000000000..469c6e2a2ce13fadc1ce6f8f525ef6c5a698914a
Binary files /dev/null and b/userguide/docs/img/device_enroll.png differ
diff --git a/userguide/docs/img/ldap.png b/userguide/docs/img/ldap.png
new file mode 100644
index 0000000000000000000000000000000000000000..0c3ba0c0b893dc3f3acd9e2e4f65562f8d72df39
Binary files /dev/null and b/userguide/docs/img/ldap.png differ
diff --git a/userguide/docs/img/local.png b/userguide/docs/img/local.png
new file mode 100644
index 0000000000000000000000000000000000000000..6809c304ebd22ca2e99cd135678982c70231c534
Binary files /dev/null and b/userguide/docs/img/local.png differ
diff --git a/userguide/docs/img/map.png b/userguide/docs/img/map.png
new file mode 100644
index 0000000000000000000000000000000000000000..e5135f992286593d1e8aca4d2ccc004dc8150d8c
Binary files /dev/null and b/userguide/docs/img/map.png differ
diff --git a/userguide/docs/img/step1.png b/userguide/docs/img/step1.png
new file mode 100644
index 0000000000000000000000000000000000000000..4753e804f99f69a722a9055eae358fb2c60e6145
Binary files /dev/null and b/userguide/docs/img/step1.png differ
diff --git a/userguide/docs/img/step2.png b/userguide/docs/img/step2.png
new file mode 100644
index 0000000000000000000000000000000000000000..49e171fe77d344335f33845e498ea1b79b78561f
Binary files /dev/null and b/userguide/docs/img/step2.png differ
diff --git a/userguide/docs/img/step3.png b/userguide/docs/img/step3.png
new file mode 100644
index 0000000000000000000000000000000000000000..60caa0e0f6dd44232b69c8a10de1fc505e026fcc
Binary files /dev/null and b/userguide/docs/img/step3.png differ
diff --git a/userguide/docs/img/step4.png b/userguide/docs/img/step4.png
new file mode 100644
index 0000000000000000000000000000000000000000..82ef819089bcc91f0666607e19b1bf27df848aec
Binary files /dev/null and b/userguide/docs/img/step4.png differ
diff --git a/userguide/docs/index.md b/userguide/docs/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..346c48c91c85d26062ff2b52c03bfc092bf44510
--- /dev/null
+++ b/userguide/docs/index.md
@@ -0,0 +1,163 @@
+# Getting Started
+
+JAMS is a server application used to enroll Jami clients into an enterprise context. Currently, JAMS supports 3 sources for user authentication: LDAP, Active Directory and an embedded database.
+
+## Obtaining Jams
+
+The current alpha build of JAMS can be downloaded at: ``https://``
+
+## System Requirements
+
+* Windows, Linux or Mac OS operating system
+* Java 11 or higher
+* 4 GB RAM
+* 1 CPU
+
+## Jams Concepts
+
+Jams was built with security in mind, therefore it is intimately related to the X509 certificate management workflows.
+
+The central concepts which are used in JAMS are the Certification Authority (CA) and the Certificate Signing Requests (CSR).
+
+In the Jams paradigm, a device (Jami client) basically requests the server to issue a certificate to it in order to present it to other devices which lets them recognize the device as a valid member of the organization, therefore Jams MUST be provided with a certificate authority in order to function correctly. Please note that a CA is NOT a standard SSL server certificate, as they do not have the permission to issue certificates.
+
+In order to be completely secure, Jams does not generate certificates for devices, but instead issues certificates based on a certificate signing request sent to it by the device, therefore removing the need to send a private key over the wire.
+
+The diagram below shows the entire process of how a device enrolls with Jams:
+
+<p align="center">
+ <img src="img/device_enroll.png" alt="Device Enrollement" style="height:250px;width:400px" />
+</p>
+
+​
+## Getting Started
+
+Download the latest version from: <https://dl.jami.net/jams/jams-alpha.zip>
+
+Unpack the ZIP file to a directory of your choice.
+
+To run the server, navigate to the directory where you have extracted the Jams package and execute ``java -jar jams-launcher.jar``
+
+## Step 1: Create your admin account
+
+This account will be used for administrative purposes, it is used to browse the user database, removing devices and performing other basic administrative tasks.
+
+<p align="center">
+ <img src="img/step1.png" alt="Create an admin account" style="height:400px;width:600px" />
+</p>
+
+
+## Step 2: Setup the Certification Authority
+
+The second step is to define your Certification Authority.
+
+<span style="color:red"> **A CA IS NOT A SERVER-SIDE SSL CERTIFICATE, IT IS A CERTIFICATE WHICH HAS THE POWER TO ISSUE OTHER CERTIFICATES. DO NOT USE THE IMPORT OPTION UNLESS
+ YOUR COMPANY'S SECURITY OFFICER HAS ISSUED YOU A CA CERTIFICATE. MOST COMMERICALLY AVAILABLE CERTIFICATES (I.E. THOSE ISSUED BY GODADDY, LETSENCRYPT, ETC... ) ARE NOT CA
+ CERTIFICATES. IF YOU ARE AN END-USER WE HIGHLY RECOMMEND YOU USE THE CREATE A SELF-SIGNED CA OPTION AS PROVIDING AN INCORRECT CERTIFICATE TYPE WILL LEAD TO A NON-FUNCTIONAL SERVER!!!** </span>
+
+<p align="center">
+ <img src="img/step2.png" alt="Create an admin account" style="height:400px;width:600px" />
+</p>
+
+This certificate will be used to sign the enrollement requests which come from Jami devices. If you are not familiar with the X509 standard, we highly recommend you read the following
+articles to get familiar with the processes and practices which surround it:
+
+<https://www.securew2.com/blog/public-key-infrastructure-explained/>
+<https://cheapsslsecurity.com/blog/understanding-the-role-of-certificate-authorities-in-pki/>
+
+## Step 3: Setup the user database
+
+Currently, Jams supports 3 sources of authentication of users:
+
+1) LDAP-compatible directory (such as OpenLDAP)
+2) Microsoft Active Directory
+3) Local embedded database
+
+<p align="center">
+ <img src="img/step3.png" width="300" height="200" style="height:400px;width:600px" />
+</p>
+
+### LDAP Authentication source
+
+If your company provides you with LDAP directory for user management, you will need to know its access information and a automated account which has read-only rights to do use look-ups.
+
+<p align="center">
+ <img src="img/ldap.png" style="height:400px;width:600px" />
+</p>
+
+Your admin should provide you most of this information but we do provide a detailed overview over each field in case you need some extra help:
+
+| Field | Details |
+| ------------- |------------- |
+| **Use StartTLS** | Your LDAP server can be configured to use either TLS/STARTTLS or PLAIN sockets, if STARTTLS is used you should mark this as true |
+| **Server Address** | The address of your server with respect to the JAMS server, your LDAP does not need to be publicly accessible but should be accessible to Jams. You should have either ``ldap://`` or ``ldaps://`` preceding the address. |
+| **Port** | The port on which the LDAP server is listening for requests (usually 389 for PLAIN/STARTTLS and 636 for SSL/TLS) |
+| **Administrator Username** | This is **NOT** the LDAP's administration account credentials, but the credentials of the account which has Read permissions to the LDAP database in order to lookup users. The format is generally ``cn=bot,ou=robots,dc=domain,dc=org`` |
+| **Password** | The password used by the account above. |
+| **BaseDN** | The base realm where the users accounts are located, in most cases it is ``ou=users,dc=company,dc=org`` |
+
+
+### Microsoft Active Directory
+
+If your company provides you with Active Directory for user management, you will need to know its access information and a automated account which has read-only rights to do use look-ups.
+
+
+<p align="center">
+ <img src="img/ad.png"style="height:400px;width:600px" />
+</p>
+
+Your admin should provide you most of this information but we do provide a detailed overview over each field in case you need some extra help:
+
+| Field | Details |
+| ------------- |------------- |
+| **Port** | The port on which Active Directory is listening (generally it is either 389 or 636) |
+| **Host** | The address of your server with respect to the JAMS server, your Active Directory does not need to be publicly accessible but should be accessible to Jams. |
+| **Administrator Username** | This is **NOT** the Active Directory's administration account credentials, but the credentials of the account which has Read permissions to the Active Directory database in order to lookup users. The format is generally ``cn=bot,ou=robots,dc=domain,dc=net`` |
+| **Password** | The password used by the account above. |
+| **Use SSL** | Whenever this server uses SSL for data transmission |
+| **Domain Name** | This is the legacy-formatted Windows Domain Name (i.e. ``WINDOMAIN``) |
+
+
+### Local Embedded Database
+
+The local database does not require any additional configuration, everything in the process is automated.
+
+<p align="center">
+ <img src="img/local.png" style="height:400px;width:600px" />
+</p>
+
+
+## Step 4: Server Parameters
+
+<p align="center">
+ <img src="img/step4.png" style="height:400px;width:600px" />
+</p>
+
+| Parameter | Details |
+| ------------- |------------- |
+| **CORS Domain Name** | The domain on which the JAMS client and administration UI will be running. |
+| **Certificate Revocation List Lifetime** | The frequency at which the CRL is updated in memory |
+| **Device Lifetime** | How long a device's certificate is valid before being considered stale and requiring re-enrollement |
+| **User Account Lifetime** | How long a user account is valid before being considered stale and requiring re-enrollement |
+
+
+<span style="color:red"> IMPORTANT NOTICE REGARDING THE FIELD **CORS Domain Name** </span> Many users have trouble with this part of the installation, to make it explicitly clear, this is web address used to access the Web UI. For example, if you expect users to access the Web UI by visiting the URL ``http://jams.mycompany.com`` then you should set the **CORS Domain Name** field to ``http://jams.mycompany.com``.
+
+## Troubleshooting and resetting
+
+If you ever need to restart from 0 (i.e. reset everything and drop existing data) you can do so by deleting the following files in the Jams directory:
+
+```
+jams.tmp/
+jams.script
+jams.properties
+tomcat.8080/
+config.json
+keystore.jks
+jams.log
+tmpjar/
+jams.lck
+```
+
+This will reset the server to its original state and you will be able to run the configuration wizard again. Please make sure to shutdown the server before
+doing performing this operation.
diff --git a/userguide/mkdocs.yml b/userguide/mkdocs.yml
new file mode 100644
index 0000000000000000000000000000000000000000..ff08086e56deeca12e76b91cc255c247808b73fa
--- /dev/null
+++ b/userguide/mkdocs.yml
@@ -0,0 +1,4 @@
+site_name: Jams User Guide
+plugins:
+ - search
+ - mkpdfs