Phoenix application generator that builds a new project skeleton configured with Carbon Five preferences and best practices baked right in. Spend less time configuring and more building cool features.
Razor generates Phoenix projects by cloning a prototype app and massaging it gently into shape.
What's in the box?
- Phoenix
- Postgrex
- Slim
- Wallaby
- ExMachina
- Yarn
- Sass
- Bootstrap
- additional acceptance environment
- CI testing via CircleCI
- .iex.exs for REPL aliases & imports
- ready for deployment to Heroku Pipelines in acceptance and prod environments.
Inspired by Carbon Five Raygun
You'll need these dependencies for Razor & your new Phoenix app:
- Erlang
- Elixir 1.4.5
- Postgres
- Yarn for JavaScript dependencies, installed and available on your path.
- Phantomjs for feature tests, installed and available on your path.
- Brunch for JavaScript builds, installed and available on your path.
You can install brunch globally or local to your project with yarn or npm.
If you install it local to your project, you'll need to add node_modules/.bin
to your path so the executable can be found.
Note for asdf users - both Razor & the generated app have a .tool-versions
file to help you get the right versions of things. You can change these - for example, erlang 19.3 is probably fine, but currently has installation problems on Macs.
mix escript.install https://github.com/carbonfive/razor/raw/master/razor_archives/razor
- Add the escript dir to your path or create a symlink, i.e.
ln -s /path/to/razor /usr/local/bin/
- Cut your app with
razor new YourAppName
- Or, if you want to install to a directory named differently from the app,
razor new YourAppName your_target_dir
cd your_new_project_dir
mix deps.get
- install dependenciesmix ecto.setup
- setup your local database- Prep js -
yarn install; brunch build
(If you have issues with this, see the "Before You Start" section above.) - Verify the test suite passes with
mix test
- Generate a secret key base with
mix phoenix.gen.secret
. You'll use this in the next step when you run your server. - Run your server with
MIX_ENV=dev SECRET_KEY_BASE= mix phoenix.server
. Use the key you just generated as the value forSECRET_KEY_BASE
. - That's it! Visit your fully-featured app at
127.0.0.1:4000
.
Windows users - your executable may be razor.bat
instead of razor
Rather than inlining the environment variables while running the server in development, we recommend using a tool that works with Procfile / .env
configs.
Heroku Local and Foreman are both good options.
A simple Procfile is provided for you. Create a .env
file in your project directory with these environment variables:
MIX_ENV=dev
SECRET_KEY_BASE=xxxxxx
You can now run your server using the tool of choice, i.e. heroku local
.
As a convenience, a weak SECRET_KEY_BASE
is hard-coded in the test
environment. You can easily change this to read an env var a la the other environments instead if needed.
Your app is pre-configured for easy deployment to Heroku w/ pipelines using CircleCI. CI is only used to run tests; your pipelines should be configured to auto-deploy branches after passing CI tests.
Convention is to auto-deploy master
branch to acceptance
, and production
branch to production
.
- Create Heroku apps for
acceptance
andproduction
- Provision Heroku Postgres DB resources
- Add buildpacks to Heroku apps
heroku buildpacks:add https://github.com/HashNuke/heroku-buildpack-elixir.git --app your-heroku-app-name
heroku buildpacks:add https://github.com/gjaldon/heroku-buildpack-phoenix-static.git --app your-heroku-app-name
- Add environment variables to Heroku
SECRET_KEY_BASE
, which can be generated with the taskmix phoenix.gen.secret
MIX_ENV
should beacceptance
andproduction
respectivelyPOOL_SIZE
should be set 2 units below the max db connections allowed by the Heroku instance. This allows mix tasks to be run with 2 connections.DATABASE_URL
should have been filled automatically by provisioning heroku postgres.
mix credo --strict
Razor fetches the latest tag from the carbonfive/razor-phoenix repo, unless it already has it cached in ~/.razor, extracts the contents of the tarball, and runs a series of search-and-replaces on the code to customize it accordingly.
This approach is fast, simple, and makes razor development very easy. Make changes to the application prototype (which is a valid phoenix app) and tag them when they should be used for new applications.
- Clone/fork Razor, make your changes & add tests
- Bump the project version # in
mix.exs
mix compile; mix build_releases
- Submit a PR