diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c08bbd5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,200 @@
+Django GUID
+
+[](https://pypi.org/pypi/django-guid)
+[](https://codecov.io/gh/snok/django-guid)
+[](https://pypi.python.org/pypi/django-guid#downloads)
+[](https://pypi.python.org/pypi/django-guid)
+[](https://img.shields.io/badge/ASGI-supported-brightgreen.svg)
+[](https://img.shields.io/badge/WSGI-supported-brightgreen.svg)
+
+
+Django GUID loads or generates [correlation IDs](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields?highlight=x-request-id#:~:text=Csrf%2DToken%3A%20i8XNjC4b8KVok4uw5RftR38Wgp2BFwql-,X%2DRequest%2DID,-%2C%5Bstackoverflow2%201)
+(also knows as request IDs) for incoming requests. Once an ID is defined, it may be attached to application
+logs as a filter. This makes it easy to correlate logs from a single HTTP request, and makes debugging simple.
+
+For the purposes of this package, a GUID (globally unique identifier) is equivalent
+to a UUID (universally unique identifier).
+
+## Examples
+
+Here is an example, containing logs from 3 different requests, with a request-id filter:
+
+```regexp
+INFO ... [773fa6885e03493498077a273d1b7f2d] project.views This is a DRF view log, and should have a GUID.
+WARNING ... [773fa6885e03493498077a273d1b7f2d] project.services.file Some warning in a function
+INFO ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.views This is a DRF view log, and should have a GUID.
+INFO ... [99d44111e9174c5a9494275aa7f28858] project.views This is a DRF view log, and should have a GUID.
+WARNING ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.services.file Some warning in a function
+WARNING ... [99d44111e9174c5a9494275aa7f28858] project.services.file Some warning in a function
+```
+
+The correlation ID makes it possible to tell which logs belong to which request. Here are the same logs, without the filter:
+
+```regexp
+INFO ... project.views This is a DRF view log, and should have a GUID.
+WARNING ... project.services.file Some warning in a function
+INFO ... project.views This is a DRF view log, and should have a GUID.
+INFO ... project.views This is a DRF view log, and should have a GUID.
+WARNING ... project.services.file Some warning in a function
+WARNING ... project.services.file Some warning in a function
+```
+
+## Installation
+
+```shell
+pip install django-guid
+```
+
+## Settings
+
+Package settings are added in your `settings.py`:
+
+```python
+DJANGO_GUID = {
+ 'GUID_HEADER_NAME': 'X-Request-ID',
+ 'VALIDATE_GUID': True,
+ 'RETURN_HEADER': True,
+ 'EXPOSE_HEADER': True,
+ 'INTEGRATIONS': [],
+ 'IGNORE_URLS': [],
+ 'UUID_LENGTH': 32,
+}
+```
+
+
+**Optional Parameters**
+
+* `GUID_HEADER_NAME`
+
+ > The name of the GUID to look for in a header in an incoming request. Remember that it's case insensitive.
+
+ Default: `Correlation-ID`
+
+* `VALIDATE_GUID`
+ > Whether the `GUID_HEADER_NAME` should be validated or not.
+ If the GUID sent to through the header is not a valid GUID (`uuid.uuid4`).
+
+ Default: `True`
+
+* `RETURN_HEADER`
+ > Whether to return the GUID (Correlation-ID) as a header in the response or not.
+ It will have the same name as the `GUID_HEADER_NAME` setting.
+
+ Default: `True`
+
+* `EXPOSE_HEADER`
+ > Whether to return `Access-Control-Expose-Headers` for the GUID header if
+ `RETURN_HEADER` is `True`, has no effect if `RETURN_HEADER` is `False`.
+ This is allows the JavaScript Fetch API to access the header when CORS is enabled.
+
+ Default: `True`
+
+* `INTEGRATIONS`
+ > Whether to enable any custom or available integrations with `django_guid`.
+ As an example, using `SentryIntegration()` as an integration would set Sentry's `transaction_id` to
+ match the GUID used by the middleware.
+
+ Default: `[]`
+
+* `IGNORE_URLS`
+ > URL endpoints where the middleware will be disabled. You can put your health check endpoints here.
+
+ Default: `[]`
+
+* `UUID_LENGTH`
+ > Lets you optionally trim the length of the package generated UUIDs.
+
+ Default: `32`
+
+## Configuration
+
+
+Once settings have set up, add the following to your projects' `settings.py`:
+
+### 1. Installed apps
+
+Add `django_guid` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+ 'django_guid',
+]
+```
+
+### 2. Middleware
+
+Add the `django_guid.middleware.guid_middleware` to your `MIDDLEWARE`:
+
+```python
+MIDDLEWARE = [
+ 'django_guid.middleware.guid_middleware',
+ ...
+ ]
+```
+
+It is recommended that you add the middleware at the top, so that the remaining middleware loggers include the requests GUID.
+
+### 3. Logging configuration
+
+Add `django_guid.log_filters.CorrelationId` as a filter in your `LOGGING` configuration:
+
+```python
+LOGGING = {
+ ...
+ 'filters': {
+ 'correlation_id': {
+ '()': 'django_guid.log_filters.CorrelationId'
+ }
+ }
+}
+```
+
+Put that filter in your handler:
+
+```python
+LOGGING = {
+ ...
+ 'handlers': {
+ 'console': {
+ 'class': 'logging.StreamHandler',
+ 'formatter': 'medium',
+ 'filters': ['correlation_id'],
+ }
+ }
+}
+```
+
+And make sure to add the new `correlation_id` filter to one or all of your formatters:
+
+```python
+LOGGING = {
+ ...
+ 'formatters': {
+ 'medium': {
+ 'format': '%(levelname)s %(asctime)s [%(correlation_id)s] %(name)s %(message)s'
+ }
+ }
+}
+```
+
+If these settings were confusing, you might find the repo examples helpful.
+
+### 4. Django GUID logger (optional)
+
+If you wish to see the Django GUID middleware outputs, you may configure a logger for the module.
+Simply add django_guid to your loggers in the project, like in the example below:
+
+```python
+LOGGING = {
+ ...
+ 'loggers': {
+ 'django_guid': {
+ 'handlers': ['console', 'logstash'],
+ 'level': 'WARNING',
+ 'propagate': False,
+ }
+ }
+}
+```
+
+This could be useful for debugging problems with request ID propagation. If a received request header containing a request ID is misconfigured, we will not raise exceptions, but will generate warning logs.