Self Hosting

Testing

If you would like to test Exceptionless locally, please follow this section. Note that this setup should NOT be used in production environments and is only for testing.

Requirements

• .NET 4.6.1
• Java JDK 1.8+
• The JAVA_HOME environment variable must also be configured when using Windows.
• IIS Express 8+
• PowerShell 3+
• Ensure a PowerShell execution policy has been set by opening a command prompt as administrator, entering powershell Set-ExecutionPolicy Unrestricted, and pressing enter.

Instructions

Perform the below steps or watch this short YouTube video.

0. Ensure all the above requirements are met.
1. Download the latest Exceptionless release artifact ZIP to your machine.
2. Unblock the ZIP file by right clicking, going to properties, clicking Unblock and then the Apply buttons, then extract the files.
3. Double click on Start.bat in the extracted folder. This will automatically launch Elasticsearch , IIS Express, and your default browser to the Exceptionless login page.

Now, you can create a local account, organization, and project (highlighted in the above video) and send errors to it to test things locally.

Production

Please follow this section to set up Exceptionless in a production environment.

Requirements

We highly recommend that you run Elasticsearch with at least a three node setup with two master nodes on Linux. We've found the Windows versions aren't as performant as the Linux versions.

• .NET 4.6.1
• IIS 7.5+
• ElasticSearch 5.1. We also have a guide located here.

Instructions

0. Ensure all the above requirements are met.
1. Download the latest Exceptionless release artifact ZIP to your machine.
2. Unblock the ZIP file by right clicking, going to properties, clicking Unblock and then the Apply buttons, then extract the files.
3. In the extracted directory, create the Logs sub-directory if it does not exist. Make sure that App_Data and the Logs directory is writable by the IIS user. To do this: Right click > Properties > Tab: Security > Edit > Select IIS_IUSRS and check the box for Full Control.
4. Setup Elasticsearch with our elasticsearch.prod.yml config. If you are using a single node Elasticsearch setup you'll need to use the single node elasticsearch.yml config. Install the Elastic Search mapper-size plugin. We also have a guide located here.
5. Setup IIS (Enable ASP.NET 4.6 and Static Content features) and add a new website pointing to the wwwroot folder that can be found inside of the extracted folder from step 3.
6. Update the Web.config file 1. ElasticSearchConnectionString should to point to your Elasticsearch servers. 1. Add the following <appSettings> keys to your web.config file. This controls how many shards and replicas each index should be created with. For a single node setup, these values should be set 1 and 0, respectively. For the recommended Elasticsearch cluster (3 nodes, two masters) the values 3 and 1 are suggested. xml <add key="ElasticSearchNumberOfShards" value="..." /> <add key="ElasticSearchNumberOfReplicas" value="..." /> 1. BaseURL should be set to the external url of the website. If you are not following the clean urls optional section below, please make sure you also add the hashbang (/#!) to the base url. 1. EnableSSL should be set to true if you have SSL certificate installed (recommended). If you do not have one for your domain, you can create a self-signed one in IIS Manager by clicking on the current server in the left pane, double clicking Server Certificates and then clicking Create self-signed certificate on the right pane that appears. 1. WebsiteMode should be set to Production if you want to send unrestricted emails. 1. Please take a quick look at the config and set any other settings to your liking (e.g., mail settings). Any property present inside Settings.cs can also be configured here.
7. Update the app.config.*.js file 1. BASE_URL should be set to the external url of the website. This value should NOT have the hashbang (/#!) appended even if it is appended in the server config. 1. USE_SSL should be set to the same value as EnableSSL in the app.config.
8. Configure your clients to send errors to your website.

Now, you can create a local account, organization, and project and send errors to it.

Optional

Redis

We recommend that you install and configure redis as it allows your app to work across multiple instances and state won't be lost when your app restarts. We highly recommend that you run Redis 3.0+ on Linux. The Windows version is an unofficial port. We've also found the Windows version to be not as reliable or performant.

0. Setup Redis 3.0+ (Linux, Windows).
1. Update the RedisConnectionString in the Web.config file to point to your Redis servers. Here is an example connection string that connects to a local Redis instance: localhost:6379,abortConnect=false.

Clean urls

You can enable clean urls (e.g., remove the hashbang #!) by following the steps below. Before continuing, please ensure that you have IIS Rewrite installed. 0. Update the Web.config file 1. Uncomment the rewrite node at the bottom of the system.webServer section. 1. Remove the /# from the end of the BaseURL setting. 1. Comment out the <remove name="RewriteModule" /> element under system.webServer\modules section. 0. Set USE_HTML5_MODE to true in the app.config.*.js file.

Active Directory Authentication

To enable Active Directory authentication, set LdapConnectionString in the <connectionStrings> section of the Web.config to your domain's LDAP URI (e.g. LDAP://ad.domain.com/ or LDAP://ad.domain.com/DC=domain,DC=com ). Please note the following: 0. Users must still go through the registration process using their AD credentials. This allows account setup to proceed as normal. AD credentials are not stored. 0. Exceptionless relies on the following properties being available in AD: * mail: user's email address * givenName: user's first name * sn: user's last name * sAMAccountName: user's username

Running jobs out of process

By default, all jobs run in process. If you find that your event processing is falling behind continually you can fire up and scale out multiple job instances. By running the jobs out of process you are responsible for ensuring all jobs are running or some functionality will not work.

0. Setup Redis by following the steps above. This allows exceptionless to communicate to the jobs that are running out of process.
1. Update the Web.config file and set the RunJobsInProcess AppSetting to false.
2. You'll need to update the job configuration settings. You can do this one of two ways: 1. Use environment variables to configure exceptionless. You can do this by adding a new environment variable with Exceptionless_{SETTING NAME} (Example: Exceptionless_BaseURL, Exceptionless_ElasticSearchConnectionString). We recommend this approach as it's easier and works great when deploying to azure. 1. Open the App_Data\jobs folder and configure each job's xxxx.exe.config with the configuration settings you have defined in your root web.config
3. Launch the jobs located in the App_Data\jobs folder and click the run.bat file to run the selected job. You can set these to run as a service or run manually.

Upgrading

Please see the Upgrading for details on how to upgrade to the current version.

Troubleshooting

If you are having issues please try the following to resolve the issues. If this doesn't work please open an issue or contact us on slack.

• Make sure you meet all the requirements and that all system updates and patches are installed. A note to Windows users: It also doesn't hurt to reboot after installing Windows updates to resolve any weird IIS issues.
• Make sure you are using our elasticsearch.yml config file. Failing to enable dynamic scripting will cause runtime issues like events not being able to be processed.
• Make sure you are running the latest release by visiting our releases page. You can verify the version you are currently running by accessing the status page http://localhost/api/v2/status.
• If you enabled Clean urls functionality and you are getting 404's when refreshing the web page. It never hurts to reinstall IIS Rewrite
• If you are not receiving emails, please ensure you have the proper email settings defined in the web.config.
• You can also enable detailed logging by updating the nlog.config minimum log level (minlevel) to Trace. This will help you diagnose the issues you are seeing. There are two ways to view the log information: 0. Open the log file that will be created in the Logs folder. 0. Create a new exceptionless project and then add the following appSettings to the web.config. After this has been done, you can view the logs in real time via the Exceptionless dashboard. Please note that if queue processing is not working, the only way to view the logs is step 1.

```