Skip to content

Self Hosting Previous Versions

Jump to bottom Edit New page
Blake Niemyjski edited this page Aug 20, 2019 · 1 revision

This document is an archive and covers self hosting the older versions of Exceptionless.

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

Instructions

Perform the below steps or watch this short YouTube video.

  1. Ensure all the above requirements are met.
  2. Download 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, then extract the files.
  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.

Instructions

  1. Ensure all the above requirements are met.
  2. Download 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, then extract the files.
  4. 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.
  5. Setup Elasticsearch. We also have a guide located here.
  6. 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.
  7. Update the Web.config file
    1. ElasticSearchConnectionString should to point to your Elasticsearch servers.
    2. 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.
      <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.
    2. 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.
    3. WebsiteMode should be set to Production if you want to send unrestricted emails.
    4. 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.
  8. 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.
    2. USE_SSL should be set to the same value as EnableSSL in the app.config.
    3. Note: if you make changes to the config file after loading a page in Exceptionless you need to do a hard refresh.
  9. 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. Comment out 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.

Enabling Slack Integrations

  1. Create a Slack app for your workspace
    • Please do not distribute your app outside of your organization.
  2. Go to the OAuth & Permissions feature. Add a new redirect URL. The redirect URL should be your Exceptionless base URL.
  3. On the basic info page of your Slack App, you will need to find the Client ID and Client Secret
  4. In your web.config, add the following keys to the configuration: 
    <add key="SlackAppId" value="Client ID here" />
<add key="SlackAppSecret" value="Client Secret here" />
  5. In your app.config.*.js file, fill out the constant for SLACK_APPID: 
    .constant('SLACK_APPID', 'Client ID here')
  6. If you've already loaded a page in Exceptionless, you will need to do a hard refresh for the config changes to apply.

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 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. 
    <add key="Exceptionless:ApiKey" value="API_KEY_OF_NEWLY_CREATED_PROJECT" />
<add key="Exceptionless:ServerUrl" value="http://BASE_URL_OF_THIS_WEBSITE_WITH_PORT" />

Documentation has been moved to https://exceptionless.com/docs/

Exceptionless Documentation

Individual Client Docs

Clone this wiki locally