Minesweeper

A minesweeper web application. The backend has been developed with the Phoenix web framework written in Elixir. The frontend has been developed with the Alpine.js JavaScript framework.

• Requirements
• Initial setup
• Run the automated tests
• Run the application in development mode
• Run the application in production mode
• Updating
• Configuration
  • Environment variables

Requirements

To run the application, you will need:

• PostgreSQL 13-17 and a database with the uuid-ossp extension

Additionally, to compile the backend and frontend, you will need:

• One of the following Elixir and Erlang/OTP combinations:
  • Elixir 1.17.x with Erlang/OTP 25-27
  • Elixir 1.16.3 with Erlang/OTP 25-26
  • Elixir 1.15.8 with Erlang/OTP 25-26
  • Elixir 1.14.5 with Erlang/OTP 25-26
• Node.js 18, 20 or 22

Initial setup

• Create a PostgreSQL user named minesweeper for the application (be sure to remember the password you type, you will need it later):

  $> sudo -u postgres createuser --interactive --pwprompt minesweeper
  Enter password for new role:
  Enter it again:
  Shall the new role be a superuser? (y/n) n
  Shall the new role be allowed to create databases? (y/n) n
  Shall the new role be allowed to create more new roles? (y/n) n

  You should answer no to all questions. The minesweeper user does not need any special privileges.

• Create a PostgreSQL database named minesweeper and owned by the minesweeper user:

  $> sudo -u postgres createdb --owner minesweeper minesweeper

• Create the uuid-ossp extension in the minesweeper database:

  $> sudo -u postgres psql -c 'CREATE EXTENSION "uuid-ossp";' minesweeper

• Clone the repository:

  $> git clone https://github.com/MediaComem/minesweeper.git

• Download dependencies:

  $> cd minesweeper
  $> mix deps.get

• Compile the application (this might take a while the first time):

  $> mix compile

• Install frontend dependencies:

  $> mix frontend.install

• Configure the application. You can do this in one of two ways:

  • Set any of the documented environment variables, for example:

    export MINESWEEPER_DATABASE_URL="ecto://minesweeper:mysecretpassword@localhost:5432/minesweeper"
    export MINESWEEPER_HTTP_PORT=3000
    export MINESWEEPER_SECRET_KEY_BASE="mysecretkey"

  • Create a local configuration file based on the provided sample:

    cp config/local.sample.exs config/local.exs

    Edit config/local.exs with your favorite editor:

    nano config/local.exs
    vim config/local.exs

    Read the instructions contained in the file and fill in the database connection URL and web endpoint settings.

    The config/local.exs file will be ignored by Git.

    Configuration parameters provided this way will be bundled in the compiled production release.

  You can use both the local configuration file and environment variables, in which case the environment variables specified at runtime will always override the corresponding settings in the configuration file.

• Migrate the production database:

  $> mix ecto.migrate

Run the automated tests

Follow these instructions to execute the project's automated test suite:

• Create a separate PostgreSQL test database named minesweeper-test also owned by the minesweeper user:

  $> sudo -u postgres createdb --owner minesweeper minesweeper-test

• Create the uuid-ossp extension in the minesweeper-test database:

  $> sudo -u postgres psql -c 'CREATE EXTENSION "uuid-ossp";' minesweeper-test

• Compile the application in test mode (this might take a while the first time):

  $> MIX_ENV=test mix compile

• Migrate the test database:

  $> MIX_ENV=test mix ecto.migrate

• Run the automated tests:

  $> MIX_ENV=test mix test

You should see no errors. Every green dot represents a passed test.

For more information, read the tests' source code in the test directory.

Run the application in development mode

You can run the application in development mode (with live reload) using the following command:

$> mix phx.server

The application runs on port 3000 by default. If that port is already in use, you can use the http.port parameter in the local configuration file or the $MINESWEEPER_HTTP_PORT environment variable to switch to another port, for example:

$> MINESWEEPER_HTTP_PORT=3001 mix phx.server

Visit http://<your-server-address>:<port> in your browser and you should see the application running.

Once you are done, you can stop the mix phx.server command running in your terminal by typing Ctrl-C twice.

Run the application in production mode

• Compile the application in production mode (this might take a while the first time):

  $> MIX_ENV=prod mix compile

• Build the frontend in production mode:

  $> MIX_ENV=prod mix do frontend.build, phx.digest

  Your reverse proxy can serve the compiled assets out of the priv/static directory.

• Assemble a mix release to run the application in production mode:

  $> MIX_ENV=prod mix release

You can run the production manually by executing the following command from the repository:

_build/prod/rel/minesweeper/bin/minesweeper start

Again, if port 3000 is already in use, you can use the http.port parameter in the local configuration file or the $MINESWEEPER_HTTP_PORT environment variable to switch to another port, for example:

$> MINESWEEPER_HTTP_PORT=3001 _build/prod/rel/minesweeper/bin/minesweeper start

To run the application with a process manager like systemd, you can run the same command except that it should be an absolute path. For example:

$> /path/to/minesweeper/_build/prod/rel/minesweeper/bin/minesweeper start

Updating

To update the application after getting the latest changes, execute the following commands in the application's directory:

# Update backend & frontend dependencies
$> mix do deps.get, frontend.update

# Apply any pending database migrations
$> MIX_ENV=prod mix ecto.migrate

# Rebuild the frontend in production mode and reassemble the Mix release
$> MIX_ENV=prod mix do frontend.build, phx.digest, release --overwrite

You may then restart the application.

Configuration

You can configure the application in two ways:

• Either create a config/local.exs file in the application's directory (see the config/local.sample.exs sample file).
• Or use the environment variables documented below.

You may also use both. The parameters in the local configuration file are bundled in the compiled production release. Note that the environment variables, if present at runtime, will always take precedence and override the corresponding parameters from the configuration file.

Environment variables

Environment variable	Default value	Description
MINESWEEPER_DATABASE_URL or DATABASE_URL	ecto://minesweeper@localhost/minesweeper	Database connection URL (format is ecto://<username>[:<password>]@<host>[:<port>]/<database-name>)
MINESWEEPER_HTTP_PORT or PORT	3000	The port the HTTP server listens on.
MINESWEEPER_SECRET_KEY_BASE	-	A secret key used as a base to generate secrets for encrypting and signing data (e.g. cookies & tokens).
MINESWEEPER_URL	http://localhost:3000	The base URL at which the application is publicly available.

You can generate a strong secret key base by running the mix phx.gen.secret command in the project's directory.