johnrlive / razor

Phoenix application generator that builds applications with the common C5 customization stuff already done.

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

Before You Start

You'll need these dependencies for Razor & your new Phoenix app:

• Erlang 18 or 19 (20 will be supported when Razor's dependencies do)
• 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.

Installing & running

• 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

Build your new project

1. cd your_new_project_dir
2. mix deps.get - install dependencies
3. mix ecto.setup - setup your local database
4. Prep js - yarn install; brunch build (If you have issues with this, see the "Before You Start" section above.)
5. Verify the test suite passes with mix test
6. Generate a secret key base with mix phoenix.gen.secret. You'll use this in the next step when you run your server.
7. Run your server with MIX_ENV=dev SECRET_KEY_BASE= mix phoenix.server. Use the key you just generated as the value for SECRET_KEY_BASE.
8. 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

Configure your development environment (optional)

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.

Deployment

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 and production
• 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 task mix phoenix.gen.secret
  • MIX_ENV should be acceptance and production respectively
  • POOL_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.

Linting

• mix credo --strict

Internal Mechanics

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.

---

Contributing to Razor

• Clone/fork Razor, make your changes & add tests
• Bump the project version # in mix.exs
• mix compile; mix build_releases
• Submit a PR