toy/README.md

Toy

This project is intended to be a (serious) playground for other Elixir projects of mine in the aspects of build, integration and deployment.

Goals

• Document build
• Implement and document cross-build
• [] Install the project as a systemd service
• Handle the current version via a git tag
• [] Build as dev or prod

Preconditions

Update Elixir's configuration to the best practices.

For some reason the default configuration of newly-generated Phoenix projects is completely outdated, e.g. using Mix.Config when the standard is now Config.

It is advised above all to update the configuration, and try to match the master branch

Setup version from a git tag

The project version is read from a git tag in the form "vX.Y.Z", provided the git hooks in priv/build/setup-git-hooks.sh are installed AND mix.exs is updated with the from_file function.

The version can then be read directly from the VERSION file or using the command : mix run -e "Mix.Project.config[:version] |> IO.puts"

This command is not really handy to run to get build metadata, though, because it requires the project to have been compiled at least once in dev mode. It is therefore more handy to read the VERSION file.

Note : do not forget to push the tags onto the origin repository !

PostgreSQL role

In dev as well as in prod modes, the role used in config/#{mode}.exs must be created using e.g. the command line : sudo -u postgres createuser -P role_name

(add -d flag to allow database creation)

PostgreSQL database

In dev as well as in prod modes, the role used in config/#{mode}.exs must be created using e.g. the command line : sudo -u postgres createdb -O role_name db_name

Running the server

In development mode

The PostgreSQL role/database must be installed, if required.

To start the server in dev mode :

• Install dependencies with mix deps.get
• Install Node.js dependencies with mix cmd npm install --prefix assets
• Start the server : mix phx.server or iex -S mix phx.server to run within a shell

The server can now be accessed on localhost:4000.

In production mode

In production mode some configuration is extracted from the environment.

• Generate a secret key using mix phx.gen.secret
• Install dependencies with mix deps.get --only prod
• Compile the application MIX_ENV=prod mix compile
• Compile static assets into priv/static : npm run deploy --prefix ./assets
• Compress and digest static assets mix phx.digest
• Start the server : MIX_ENV=prod DATABASE_URL=db-url SECRET_KEY_BASE=secret_key PORT=port mix phx.server

Getting the latest release

The latest release can be easily found using the following shell command : find _build/prod/ -name "*.tar.gz" -exec stat -c "%n %Y" {} \; | sort -rnk 2,2 | head -1 | cut -d ' ' -f 1 | xargs realpath

To find the directory of the latest release : find _build/prod/rel/app_name/releases -type d -exec stat -c "%n %Y" {} \; | sort -rnk 2,2 | head -1 | cut -d ' ' -f 1 | xargs realpath