npm package: @marathonhq/marathon
Description: Enterprise Grade User Management System
Author: John Rocela
Latest version: 1.0.0

# Marathon

Painless User Management

[![CircleCI](https://circleci.com/gh/marathonhq/marathon.svg?style=svg)](https://circleci.com/gh/marathonhq/marathon)

Visit [trymarathon.com/learn](https://trymarathon.com/learn) to get started.

## What is Marathon?

User Management is a wheel that has been reinvented again and again, from platform to platform, across thousands of projects. However, there are tons of principles and rules that are consistent and could be standardized. What if the next project you are tasked with won't require you to redo the user management paradigm, but instead, install it like with any other server dependency you have.

Marathon is an open source software that bootstraps standard User Management paradigms that can be deployed to any infrastructure.

### Vision

Marathon aims to be the de-facto user management system that developers can deploy and forget with considerations on being agnostic, extensible, secure, simple, and familiar while also providing a way to "exit" and avoid lock-in.

### Roadmap

[Marathon's Public Roadmap](https://github.com/marathonhq/marathon/projects/1)
is available to everyone's suggestion and contribution. Please create a [Github Issue](https://github.com/marathonhq/marathon/issues/new) with the `enhancement` label so I can review it and add it to the roadmap.

### Status

Marathon is currently **in development** and not in a stable state. It is not recommended to use Marathon in production at the moment. Development started in February 2019.

## Installation and Setup

### Quick Start

Install the Marathon CLI.

#### via NPM

```
npm install -g marathon-cli
```

#### via Brew

```
brew install marathon-cli
```

Run the Marathon installation script via the `create` command:

```
$ marathon-cli create project-name --env=development
```

After installation has finished, navigate to http://localhost:41140 and [complete the set up process](https://trymarathon.com/docs/install/complete) via the Installation UI.

If you do not want to use the installation UI, you can [create an installation configuration](https://trymarathon.com/docs/deploy/installation) instead.

#### via docker-compose

If you want to run Marathon via or docker-compose, you can fetch the relevant docker files within `/install/docker` and run:

```
$ docker-compose --file install/docker/docker-compose.yml up --detach
```

The resulting image that will run will have all the plugins and services loaded and db migrations migrated. If you wish to customize the installation, check out how to [Configure Marathon](https://trymarathon.com/docs/configuring).

### Migration

The installation command should migrate into your selected database. If you would like to run it manually, use the following command:

```
$ marathon-cli migrate project-name --env=development
```

## Documentation

- [Getting Started](https://trymarathon.com/docs/getting-started)
- [Configuring Marathon](https://trymarathon.com/docs/configuring)
- [Installation](https://trymarathon.com/docs/install)
  - [via Local Machine](https://trymarathon.com/docs/install/local)
  - [via Docker](https://trymarathon.com/docs/install/docker)
  - [via Vagrant](https://trymarathon.com/docs/install/vagrant)
  - [Completing an Installation](https://trymarathon.com/docs/install/complete)
- [Services](https://trymarathon.com/docs/services)
  - [Consumer](https://trymarathon.com/docs/services/consumer)
  - [Administrator](https://trymarathon.com/docs/services/administrator)
  - [Authenticator](https://trymarathon.com/docs/services/authenticator)
  - [Analytics](https://trymarathon.com/docs/services/analytics)
- [Plugins](https://trymarathon.com/docs/plugins)
  - [Feed](https://trymarathon.com/docs/plugins/feed)
  - [Gamify](https://trymarathon.com/docs/plugins/gamify)
  - [SAML](https://trymarathon.com/docs/plugins/saml)
  - [Subscriptions](https://trymarathon.com/docs/plugins/subscriptions)
  - [Messages](https://trymarathon.com/docs/plugins/messages)
- [Testing](https://trymarathon.com/docs/testing)
- [Workers](https://trymarathon.com/docs/workers)
- [Deployment](https://trymarathon.com/docs/deploy)
  - [Installation Configuration](https://trymarathon.com/docs/deploy/installation)
  - [to AWS Cloudformation](https://trymarathon.com/docs/deploy/aws-cloudformation)
  - [to AWS Elasticbeanstalk](https://trymarathon.com/docs/deploy/aws-elasticbeanstalk)
  - [to DigitalOcean](https://trymarathon.com/docs/deploy/digitalocean)
  - [to Kubernetes](https://trymarathon.com/docs/deploy/kubernetes)
- [API References](https://trymarathon.com/api)
- [CLI](https://trymarathon.com/docs/cli)
  - [Create](https://trymarathon.com/docs/cli/create)
  - [Migrate](https://trymarathon.com/docs/cli/migrate)
  - [Eject](https://trymarathon.com/docs/cli/eject)
- [Contribution](https://trymarathon.com/docs/contribution)
  - [Creating a New Service](https://trymarathon.com/docs/services/new)
  - [Creating a New Plugin](https://trymarathon.com/docs/plugins/new)

## Development Decisions

...

## Terms

- Services - HTTP facing services
  - Controllers - Serialization, Validation, and generic HTTP methods
  - Middlewares - Service specific http middlewares
  - Repositories - Business Domain Logic
  - Schema - Validate against incoming requests and outgoing responses
- Plugins - Feature enhancements hooked via the event system and http lifecycle
- Database/Models - DB Convenience methods
- Database/Schema - Schema when inserting information to the database

### Why not use Typescript/Flow?

I want to allow modification that is not hindered by the additional effort of learning a typed language. However, the codebase is littered with type definitions to allow for a simpler developer experience.

### Why is this a Monolith?

The focus of the system is to bootstrap a user management system with a reasonable amount of time for setup and maintenance. Having a monolith answers this initial requirement. However, the system can be configured to run specific services separately. Learn more about [Deployment](https://trymarathon.com/docs/deploy) here.

## Have Issues?

Please create a [Github Issue](https://github.com/marathonhq/marathon/issues/new) so I can review and add it to succeeding versions. Please make sure to follow the issue template.

## FAQ

<details>
<summary>Is Marathon production ready?</summary>

No. At the moment, please use Marathon as a playground and development test bed. A stable release will come in June 2019.

</details>
<details>
<summary>Isn't this like Auth0/Firebase/Parse?</summary>

Yes, and no. Marathon only aims to be a user management system that any system can rely and extend from. The data stored by Marathon is owned by the developer/company that installed and maintains the Marathon instance.

</details>
<details>
<summary>How secure is it?</summary>

Security still relies on the developer's/company's discretion. Standard security practices apply when deploying this software to production.

</details>
<details>
<summary>I don't want to use Marathon anymore, how do I get my data?</summary>

Marathon conveniently provides away to "eject" from the system. You can run `marathon-cli eject 10.0.0.1` to download a snapshot of the current database. See the [Eject](https://trymarathon.com/docs/cli/eject) command from the CLI to know more.

</details>
<details>
<summary>Can I modify the source code?</summary>

Yes! The MIT license permits you to do so. But Please remember to give credit to the original source code.

</details>
<details>
<summary>Can you host an instance for my company?</summary>

I am looking into creating managed instances for Marathon with simple pricing. Stay tuned for more information.

</details>
<details>
<summary>What sort of security certification does Marathon have?</summary>

At the moment, Marathon holds none. Once I provide service via managed instances, we will make this as a hard requirement.

</details>
<details>
<summary>Where can I get support?</summary>

At the moment, you can email `john@marathon.sh` directly for support. Allow a day or two for a response. Else, please proceed to [Github Issue](https://github.com/marathonhq/marathon/issues/new) and submit an issue there. Please make sure to follow the issue template.

</details>
<details>
<summary>Can I buy you coffee?</summary>

Yes! I highly appreciate it. Send me an email and I'll send you my Paypal Account.

</details>

## Contributing

If you wish to contribute to the core code, please see [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

Licensed under MIT, see the [LICENSE](./LICENSE) file.