Skip to content

Commit

Permalink
Improve a few sections of README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@remi
remi committed Apr 7, 2018
1 parent 4f49e2b commit ab81cb8
Showing 1 changed file with 43 additions and 39 deletions.
82 changes: 43 additions & 39 deletions README.md
View file
@@ -1,5 +1,5 @@
<p align="center">
<img src="logo.svg" alt="Accent Logo" width=500 />
<img src="logo.svg" alt="Accent Logo" width="500" />
</p>

[Website](https://www.accent.reviews) • [GraphiQL](https://www.accent.reviews/documentation)
Expand Down Expand Up @@ -28,80 +28,84 @@ The Accent API provides a powerful abstraction around the process of translating

## Requirements

- Erlang OTP 20.1
- Elixir 1.6.2
- PostgreSQL >= 9.4
- Node.js >= 8.5.0
- libyaml
- `erlang ~> 20.1`
- `elixir ~> 1.6.0`
- `postgres >= 9.4`
- `node.js >= 8.5.0`
- `libyaml >= 0.1.7`

## Executing mix commands

The app is modeled with the _Twelve-Factor_ architecture, all configurations are stored in the environment.
The app is modeled with the [_Twelve-Factor App_](https://12factor.net/) architecture, all configurations are stored in the environment.

When executing mix command, you should always make sure that the required system `ENV` are present. You can `source`, use [nv](https://github.com/jcouture/nv) or a custom l33t bash script.
When executing `mix` commands, you should always make sure that the required environment variables are present. You can `source`, use [nv](https://github.com/jcouture/nv) or a custom l33t bash script.

Every following steps assume you have this kind of system.
But Accent can be run with default env var if you have a PostgreSQL user named postgres listening on port 5432 on localhost.

But Accent can be run with default environment variables if you have a PostgreSQL user named `postgres` listening on port `5432` on `localhost`.

### Example

With `nv` you inject the environment keys in the context with:

```shell
> nv .env mix <mix command>

```
$ nv .env mix <mix command>
```

## Quickstart

1. If you don’t already have it, install `nodejs` with `brew install nodejs`
1. If you don’t already have it, install `elixir` with `brew install elixir`
2. If you don’t already have it, install `libyaml` with `brew install libyaml`
2. If you don’t already have it, install `PostgreSQL` with `brew install postgres` or the [macOS app](https://postgresapp.com/)
3. Install dependencies with `mix deps.get` and `npm --prefix webapp install`.
4. Create and migrate your database with `mix ecto.setup`
5. Start Phoenix endpoint with `mix phx.server`
5. Start Ember server with `npm --prefix webapp run start`
6. That’s it.
1. If you don’t already have it, install `nodejs` with `brew install nodejs`
1. If you don’t already have it, install `elixir` with `brew install elixir`
2. If you don’t already have it, install `libyaml` with `brew install libyaml`
2. If you don’t already have it, install `postgres` with `brew install postgres` or the [macOS app](https://postgresapp.com/)
3. Install dependencies with `mix deps.get` and `npm --prefix webapp install`.
4. Create and migrate your database with `mix ecto.setup`
5. Start Phoenix endpoint with `mix phx.server`
5. Start Ember server with `npm --prefix webapp run start`
6. That’s it!

## Environment variables

This app provides default value for every env var. This means that with the right PostgreSQL setup, you can just run `mix phx.server`.
Accent provides a default value for every required environment variable. This means that with the right PostgreSQL setup, you can just run `mix phx.server`.

- `DATABASE_URL=postgres://localhost/accent_development`: A valid database url. Like the one used by Heroku.
- `PORT=4000`: A PORT to run your app.
- `WEBAPP_PORT=4200`: A PORT to run your webapp. (only used in dev)
- `API_HOST=http://localhost:4000`: The host of the API.
- `API_WS_HOST=ws://localhost:4000`: The websocket host of the API.
- `MIX_ENV=dev` : Environment to run mix {dev, prod, test}
- `WEBAPP_EMAIL_HOST=localhost:8001`: Web client’s hostname. Used in the sent emails to link to the right URL. There is no default value, please provide a value if you want to send emails.
- `MAILER_FROM=anEmail@gmail.com`: Email address used in the sent email. There is no default value, please provide a value if you want to send emails.
| Variable | Default | Description |
|---------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `MIX_ENV` | `dev` | The application environment (`dev`, `prod`, or `test`) |
| `DATABASE_URL` | `postgres://localhost/accent_development` | A valid database URL |
| `PORT` | `4000` | A PORT to run the API on |
| `WEBAPP_PORT` | `4200` | A PORT to run the Webapp on (only used in `dev` environment) |
| `API_HOST` | `http://localhost:4000` | The API host |
| `API_WS_HOST` | `ws://localhost:4000` | The API Websocket host |
| `WEBAPP_EMAIL_HOST` | _none_ | The Web client’s hostname. Used in the sent emails to link to the right URL. There is no default value, please provide a value if you want to send emails. |
| `MAILER_FROM` | _none_ | The email address used to send emails. There is no default value, please provide a value if you want to send emails. |

### Production setup

- `SENTRY_DSN`
- `WEBAPP_SENTRY_DSN`
- `GOOGLE_API_CLIENT_ID`: When deploying in a production env, the Google login is the only way to authenticate user. In dev, a fake login provider is used so you don’t have to setup a Google app.
| Variable | Default | Description |
|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `SENTRY_DSN` | _none_ | The *secret* Sentry DSN used to collect API runtime errors |
| `WEBAPP_SENTRY_DSN` | _none_ | The *public* Sentry DSN used to collect Webapp runtime errors |
| `GOOGLE_API_CLIENT_ID` | _none_ | When deploying in a `prod` environment, the Google login is the only way to authenticate user. In `dev` environment, a fake login provider is used so you don’t have to setup a Google app. |

## Tests

### API

This app provides default value for every env var required in test. This means that with the right PostgreSQL setup, you can just run `mix test`.
Accent provides a default value for every required environment variable. This means that with the right PostgreSQL setup (and a few setup commands), you can just run `mix test`.

```shell
```
$ npm --prefix webapp run build
$ mix run ./priv/repo/seeds.exs
$ mix test
```

## Deploy on Heroku

To successfully deploy the application on Heroku, you must use these buildpacks:
To successfully deploy Accent on Heroku, you must use these buildpacks:

_The first buildpack is to use the Aptfile to install libyaml._

```shell
```
$ heroku buildpacks:add --index 1 https://github.com/heroku/heroku-buildpack-apt#usr-local-paths
$ heroku buildpacks:add --index 2 https://github.com/HashNuke/heroku-buildpack-elixir
$ heroku buildpacks:add --index 3 https://github.com/gjaldon/heroku-buildpack-phoenix-static
Expand All @@ -111,12 +115,12 @@ $ heroku buildpacks:add --index 3 https://github.com/gjaldon/heroku-buildpack-ph

Before opening a pull request, please open an issue first.

Once you've made your additions and the test suite passes, go ahead and open a PR!
Once you’ve made your additions and the test suite passes, go ahead and open a PR!

Don’t forget to run the `./priv/scripts/ci-check.sh` script to make sure that the CI build will pass :)

## About Mirego

[Mirego](https://www.mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We're a team of [talented people](https://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://www.mirego.org).
[Mirego](https://www.mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We’re a team of [talented people](https://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://www.mirego.org).

We also [love open-source software](https://open.mirego.com) and we try to give back to the community as much as we can.

0 comments on commit ab81cb8

Please sign in to comment.