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.

1. Ensure all the above requirements are met.
2. Extract the latest Exceptionless release artifact ZIP to your machine.
3. Unblock the ZIP file by right clicking, going to properties, clicking Unblock and then the Apply buttons.
4. 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 1.7.5 (Elasticsearch 2.x and later versions (Up to version 5.x) is not yet supported). We also have a guide located here.

Instructions

1. Ensure all the above requirements are met.
2. Extract the latest Exceptionless release artifact ZIP to your machine.
3. Unblock the ZIP file by right clicking, going to properties, clicking Unblock and then the Apply buttons.
4. Setup Elasticsearch (Linux, Windows) with our elasticsearch.yml config. If you are using a single node Elasticsearch setup you'll need to use the single node elasticsearch.yml config. 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 2.
6. Update the Web.config file 1. ElasticSearchConnectionString should to point to your Elasticsearch servers.
   1. If you are using a single node Elasticsearch setup please skip this step. Add the following <appSettings> keys to your web.config file. This controls how many shards and replicas each index should be created with.

     <add key="ElasticSearchNumberOfShards" value="3" />
     <add key="ElasticSearchNumberOfReplicas" value="1" />

2. `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.
3. `EnableSSL` should be set to true if you have SSL certificate installed (recommended).
4. `WebsiteMode` should be set to `Production`.
5. Please take a quick look at the config and set any other settings to your liking (e.g., mail settings).

7. Update the app.config.*.js file 1. BASE_URL should be set to the external url of the website. 2. USE_SSL should be set to true if you have SSL certificate installed (recommended).
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.

1. Setup Redis 3.0+ (Linux, Windows).
2. 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.

1. Update the Web.config file 1. Uncomment the rewrite node at the bottom of the system.webServer section. 2. Remove the /# from the end of the BaseURL setting. 3. Uncomment the <remove name="RewriteModule" /> element under system.webServer\modules section.
2. 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:

1. 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.
2. 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.

1. Setup Redis by following the steps above. This allows exceptionless to communicate to the jobs that are running out of process.
2. Update the Web.config file and set the RunJobsInProcess AppSetting to false.
3. 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. 2. 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
4. 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 ensure that you have created backups before upgrading!

If you are upgrading from v1 or v2 you will need to upgrade to v3.0 before upgrading to the latest release.

After you've followed the steps below to upgrade to the v3.0.0 release. You can the follow setup section above to finish upgrading to the latest version of Exceptionless.

Upgrading from v2 to v3

Please note that upgrading from v2 to v3 requires that Redis is installed and configured.

1. Download and extract the v3 release to a temp folder.
2. Update the connection strings in the App_Data\JobRunner\Job.exe.config config file.

   1. You'll also need to add a Migration:MongoConnectionString connection string for the migration jobs to run.

      <add name="Migration:MongoConnectionString" connectionString="mongodb://localhost/exceptionless" />

3. Open the terminal and run the following jobs to migrate data from previous major versions of Exceptionless. Jobs.exe can be found in the \wwwroot\App_Data\JobRunner\ folder.

Job.exe -t "Exceptionless.EventMigration.OrganizationMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core"

Upgrading from v3 to v4

In Progress

Upgrading from v1 to v3

Please note that upgrading from v1 to v3 requires that Redis is installed and configured.

1. Download and extract the v3 release to a temp folder.
2. Update the connection strings in the App_Data\JobRunner\Job.exe.config config file.

   1. You'll also need to add a Migration:MongoConnectionString connection string for the migration jobs to run.

      <add name="Migration:MongoConnectionString" connectionString="mongodb://localhost/exceptionless" />

3. Open the terminal and run the following jobs to migrate data from previous major versions of Exceptionless. Jobs.exe can be found in the \wwwroot\App_Data\JobRunner\ folder.

Job.exe -t "Exceptionless.EventMigration.StackMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core"
Job.exe -t "Exceptionless.EventMigration.QueueEventMigrationsJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core"
Job.exe -t "Exceptionless.EventMigration.EventMigrationJob, Exceptionless.EventMigration" -c -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core"
Job.exe -t "Exceptionless.EventMigration.OrganizationMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core"

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:
  1. Open the log file that will be created in the Logs folder.
  2. 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.

```