diff --git a/README.md b/README.md index ccca5acd5..d9eeb46de 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Accent Logo + Accent Logo

[Website](https://www.accent.reviews) • [GraphiQL](https://www.accent.reviews/documentation) @@ -28,68 +28,72 @@ 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 - +``` +$ nv .env mix ``` ## 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 @@ -97,11 +101,11 @@ $ 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 @@ -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.