b3k / razor

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

alt tag

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.
  • 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 --name YourAppName --dir your_target_dir

Build your new project

  • cd your_new_project_dir
  • mix deps.get - install dependencies
  • mix 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.
  • Create a .env file with variables MIX_ENV=dev and SECRET_KEY_BASE=your_secret_key_base.
    Run mix phoenix.gen.secret to generate a good value for SECRET_KEY_BASE.
  • Set dev mode locally with echo -n 'export MIX_ENV=dev' >> .env
  • Verify the test suite passes with mix test
  • Run with heroku local/foreman, or load your secret key base from .env & run phoenix
  • source .env; mix phoenix.server
  • That's it! Visit your fully-featured app at localhost:4000.

Windows users - your executable may be razor.bat instead of razor

Deployment

This 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 prod 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 developement 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

About

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


Languages

Language:Elixir 100.0%