Skip to content

Self Hosting Docker

Blake Niemyjski edited this page Apr 11, 2019 · 6 revisions

WIP - This will replace the existing self hosting guide when complete

Docker

If you would like to test Exceptionless locally, please follow this section.

Requirements

Instructions

  1. Clone this repository or download the latest Exceptionless release artifact ZIP to your machine.
  2. Open your terminal in the cloned or extracted directory and run docker-compose up. Please note you can run docker-compose up -d to run docker in the background. This is the recommended approach for self hosting.
  3. Launch your default browser http://localhost:5000 to view the Exceptionless login page.

Now, you can create an account, organization, and project to send in new events.

Considerations.

  • We recommend that you look into running elasticsearch inside of a cluster.
  • Please remember to tweak the memory requirements for elasticsearch inside of the docker-compose file.

Kubernetes

Please follow this section to set up Exceptionless in a Kubernetes environment. Please note this section is a work in progress, any contributions is greatly appreciated.

Requirements

Instructions

Please note that we recommend you use Kubernetes for running in production. However, if you do not want to use Kubernetes then please follow the configuration steps below with the test instructions above. You'll need to run docker-compose up -d in step #2 of the test instructions to run the services in the background.

  1. Clone this repository or download the latest Exceptionless release artifact ZIP to your machine.
  2. TODO, but for now follow the steps here for how to create it in AKS
  3. View the configuration settings below for more information on configuring exceptionless.
  4. Configure your clients to send errors to your website.

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

Configuration

The following section will cover how to configure exceptionless inside of a Kubernetes instance using the exceptionless-config config map. All exceptionless configuration keys are prefixed with EX_. Please note that these instructions also apply to docker using environment variables.

All configuration options and settings can be found in the various option classes located here.

Please note that if you are specifying configuration via docker-compose, then you will need to drop the EX_ and EX_ConnectionStrings__ prefixes.

ConnectionStrings

# connection string used for any provider specifying Redis. 
EX_ConnectionStrings__Redis: server=localhost:6379,abortConnect=false

EX_ConnectionStrings__Cache: provider=redis;
EX_ConnectionStrings__Elasticsearch: server=http://10.0.0.4:9200;
EX_ConnectionStrings__Email: smtps://user%40domain.com:password@smtp.domain.com:465
EX_ConnectionStrings__MessageBus: provider=redis;
EX_ConnectionStrings__Metrics: provider=statsd;server=localhost
EX_ConnectionStrings__Queue: provider=redis;
EX_ConnectionStrings__Storage: provider=azurestorage;

You can append values to any connection string using a ;. For example, you can control many shards and replicas each Elasticsearch index should be created with by appending to the EX_ConnectionStrings__Elasticsearch connection string. For a Elasticsearch cluster (3 nodes, two masters), you would append shards=3;replicas=1.

The provider value determines what implementations to use for the various abstractions. We've made it easier to reuse a single connection string by automatically looking up a connection string by the provider name and adding any key value pairs to the current connection string (as shown above with redis).

General Configuration

  1. You'll want to set the EX_ApiUrl key to your external url of the api.
  2. You'll want to set the EX_BaseUrl key to your 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. EX_AppMode should be set to Production if you want to send unrestricted emails.
  4. Please take a quick look at all the configuration options and settings that can be found in the various option classes located here.

Active Directory Authentication

To enable Active Directory authentication, update the Update the exceptionless-config config map to include the EX_ConnectionStrings__LDAP connection string. The value should be 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

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. Update the exceptionless-config config map ConnectionStrings__OAuth value to include SlackId=YOUR_ID;SlackSecret=YOUR_SECRET; and restart the associated pods.
  5. 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 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/about.
  • You can also enable detailed logging by updating the Serilog__MinimumLevel__Default config map value to Debug.
You can’t perform that action at this time.