====== Installing the RePoSyD REST API ======

Open a command prompt and run the following command:

<cli prompt="C:\> ">
C:\> reposyd init c:\temp\reposyd
info: root folder 'c:/temp/reposyd' created.
info: intalling RePoSyD packages...
info: RePoSyD packages installation completed
info: creating RePoSyD configuration file...
info: initializing repository...
info: initialization completed
url      sqlite:c:/temp/reposyd/database?database=reposyd.sqlite
schema   0.34.0
account  admin
password gukidaka
uuid     {e6700c3e-f17f-455f-a6a0-92d45dadd3ab}
</cli>

<WRAP center round important 60%>
Write down the automatically generated password.
</WRAP>

If you don't want to use an autogenrated password, you specify your own password using the CLI option --password.

<cli prompt="C:\> ">
C:\> reposyd init c:\temp\reposyd --password <mypassword>
</cli>

==== Folder Structure ====

^Folder ^^^ Content ^
|**<root>**  |||Root folder of the installation.|
|  |app ||Contains the files of the RePoSyD Web Application |
| |config ||Configuation files, e.g. RePoSyD API config. |
| |data || |
| | |backup | |
| | |database |Location of the database files. |
| | |log |Log files |
| | |templates |Templates for email generation.|
| |service || |
 
==== Configuration ====

The RePoSyD server is customizable through the configuration file.

=== Application ===

^ Key | Default |Type | Usage ^
| **application** ||
| application.url | http://localhost | string | Application URL. Used, for example, for HTTP links in emails. |

=== Authentification ===

^ Key | Default |Type | Usage ^
| authentification | [repository] | string%%|%%object[] | List of the strategies for user authentification |

=== Available Strategies ===

== Repository ==

This is the default strategy for authenticating a user.

<code json>{
  "authentification": ["repository"]
}</code>

== LDAP Server ==

<code json>{
  "authentification": [{
    "type": "ldap",
    "ldap": {
      "url": "ldaps://localhost:636"
      "users": {
        "attribteName": "cn",
        "dn": "cn={{username}},ou=users,dc=test"
        "searchBase": "cn=Users,dc=test",
      },
        "groups": {
        "attributeName": "dn",
        "groupName": "RePoSyD User",
        "memberAttribute": "member",
        "objectClass": "group",
        "searchBase": "cn=Users,dc=test"
       },
     }
  }]
}</code>

== Active Directory Server ==

<code json>{
  "authentification": [{
    "type": "ldap",
    "ldap": {
      "url": "ldaps://localhost:389"
      "users": {
        "attribteName": "sAMAccountName",
        "dn": "DOMAIN\{{username}}"
        "searchBase": "ou=users,dc=test",
      },
        "groups": {
        "attributeName": "cn",
        "groupName": "reposyd",
        "memberAttribute": "member",
        "objectClass": "group",
        "searchBase": "ou=group,dc=reposyd,dc=test"
       },
     }
  }]
}</code>

**IIS Web Config**
<code>
<rewrite>
  <rules>
    <clear/>
    <rule name="RePoSyD API" enabled="true" stopProcessing="true">
      <match url="^api/(.*)"/>
      <conditions logicalGrouping="MatchAll" trackAllCaptures="false"/>
      <action type="Rewrite" url="http://localhost:3000/{R:1}"/>
    </rule>
    <rule name="RePoSyD Auth" enabled="true" patternSyntax="ECMAScript" stopProcessing="true">
      <match url="^auth/(.*)"/>
      <conditions logicalGrouping="MatchAll" trackAllCaptures="false"/>
      <action type="Rewrite" url="http://localhost:3000/auth/{R:1}" logRewrittenUrl="true"/>
    </rule>
  </rules>
  <outboundRules>
    <preConditions>
      <preCondition name="ResponseIsHtml1">
        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html"/>
      </preCondition>
    </preConditions>
  </outboundRules>
</rewrite>
</code>

== HTTPS Redirect ==
<code>
<rule name="HTTPS-Redirect" stopProcessing="true">
  <match url="(.*)"/>
  <conditions>
    <add input="{HTTPS}" pattern="^OFF$"/>
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}{REQUEST_URI}" appendQueryString="false"/>
</rule>
</code>
=== EMail ===

^ Key | Default |Type | Usage ^
| **email** ||
| email.preview | false | boolean | If true, the email preview is shown in the default browser and **not** send. Should be used for development purposes only. |
| email.replyAddress | | string | Reply address used in emails. |
| email.supportAddress | | string | Mail address of the support organization maintaining RePoSyD. |
| email.templates | | string | Folder containing the templates used for generating emails. |

=== Event Handler ===

^ Key | Default |Type | Usage ^
| eventHandler | ["actiontracking", "repository", "role"] | string[] | List of activated event handlers. |

=== Built-in Event Handler ===

== Action Tracking ==

Sends a notification email to action responsible.

== Event Logger ==

Captures all events and writes them to the log as debug output (logging level: "debug".

== Repository ==

== Role ==





=== JSON Web Token (JWT) ===

^ Key | Default |Type | Usage ^
| **jwt** ||
| jwt.secret | null | string | secret key used to encrypt the tokens. If null or undefined, the internal secret key is generated. \\ <label type="danger">!! SECURITY WARNING!!</label>\\  <wrap em>DO NOT USE THE SECRET OPTION IN A PRODUCTION ENVIRONMENT, UNLESS YOU KNOW WHAT YOU ARE DOING!</wrap> |
| jwt.ttl.access | 360s | string | Time to live for the access token, expressed in seconds or a string describing a time span [[https://github.com/vercel/ms|vercel/ms]]. |
| jwt.ttl.refresh | 24h | string | Time to live for the refresh token, expressed in seconds or a string describing a time span [[https://github.com/vercel/ms|vercel/ms]]. |

=== Logging ===

^ Key | Default |Type | Usage ^
| **logging** ||
| logging.level | info | string | |
| logging.console.enabled | false | boolean | If true, messages are displayed on the console (stdout). |
| logging.file.enabled | false | boolean | If true, messages are written in the specified log file. |
| logging.rotation.enabled | false | boolean | If true, log file rotation is enabled. |
| logging.rotation.createSymlink | false | boolean | Create a tailable symlink to the current active log file |
| logging.rotation.folder | . | string | The folder name to save log files to. |
| logging.rotation.maxSize | 500k | string | Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number. |
| logging.rotation.maxFiles | 14d | string | Maximum number of logs to keep. If not set, no logs will be removed. This can be a number of files or number of days. If using days, add 'd' as the suffix. It uses auditFile to keep track of the log files in a json format. It won't delete any file not contained in it. It can be a number of files or number of days. |
| logging.rotation.symlinkName| reposyd.log | string | The name of the tailable symlink. |
| logging.rotation.utc | true | boolean | Use UTC time for date in filename. |
| logging.rotation.zippedArchive | true | boolean | If true, the archived log files are gzipped. |

=== Repository ===

^ Key | Default |Type | Usage ^
| **repository** ||
| repository.url | | string | URL of the repository, e.g. 'sqlite:/var/opt/reposyd/database?database=reposyd.sqlite' |

=== Restify ===

^ Key | Default |Type | Usage ^
| **restify** ||
| restify.host | localhost | string | Specifies the host interface on which the restify listens. Use '0.0.0.0' to listen on all interfaces. |
| restify.port | 3000 | string | Port number on the interface. |
| restify.ssl.cert | | string | |
| restify.ssl.key| | string | |

=== Services ===
^ Key | Default | Type | Usage ^
| services | ["actiontracking"] | string|object[] | List of activated services. |

=== Built-in Services  ===

== Action Tracking ==

The action tracking services generates emails for overdue actions and sends them to the responsible users.
For using the default configuration, add a string value to the list of activated services.
<code>"services": ["actiontracking"]</code>
To run the service with custom option, add a object value to the list.
<code>"services": [{ "name": "actiontracking", "whine": { "interval": "* * * 12" } }]
</code>

^ Key | Default | Type | Usage ^
| whine.interval | * * !6-7 12" | string | The string value defines the interval for whining about overdue actions. [[https://www.npmjs.com/package/timexe|timexe]] \\ In the default configuration, the service is executed from Monday to Friday at 12 noon. |


=== SMTP ===

^ Key |  Default |Type | Usage ^
| **smtp**  ||
| smtp.host | | string | This option specifies the SMTP used for sending messages. To use the local SMTP, set this option to 'localhost'. Otherwise use a fully qualified domain name. |
| smtp.port | 25 | number| This option specifies the SMTP port to use.  |
| smtp.user | | string | Username for SMTP server authentification. |
| smtp.password | | string | Password used for SMTP server authentification |
| smtp.check | false | boolean | If true, the SMTP server connection is checked at startup. |
| smtp.secure | false | boolean | If true the connection will use TLS when connecting to server. If false (the default) then TLS is used if server supports the STARTTLS extension. In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false |
| smtp.tls.rejectUnauthorized | false | boolean | If true, the server certificate is **not** validated against the list of CAs. |
| smtp.tls.ignore | false | boolean | If true and secure is false then TLS is not used even if the server supports STARTTLS extension. |
| smtp.tls.require | false | boolean | If this is true and secure is false then Nodemailer tries to use STARTTLS even if the server does not advertise support for it. If the connection can not be encrypted then message is not sent |

=== Configuration File ===
== Example Development Environment ==

<file reposyd.json>
{
  "application": {
    "url": "http://localhost"
  },
  "authentification": ["repository"],
  "jwt": {
    "secret": "!!##@@changeme@@##!!"
  },
  "logging": {
    "console": {
      "enabled": true
    },
    "file": {
      "enabled": false
    },
    "rotation": {
      "enabled": false
    },
    "syslog": {
      "enabled": false
    },
    "level": "debug",
    "service": "reposyd-devel"
  },
  "eventHandler": ["actiontracking", "repository", "role"],
  "services": [
    {
      "name": "actiontracking",
      "debug": false,
      "whine": {
        "atStartup": false,
        "interval": "* * !6-7 12"
      }
    }
  ],
  "repository": {
    "url": "sqlite:d:/reposyd/carbcat/database?database=reposyd.sqlite"
  },
  "restify": {
    "host": "127.0.0.1",
    "port": 3000
  }
}

</file>