From d145640ead57d2bc913b72fb4d4fff4cdd3beb47 Mon Sep 17 00:00:00 2001 From: Jyri-Petteri Paloposki Date: Sun, 19 Jul 2020 23:06:26 +0300 Subject: [PATCH] =?UTF-8?q?Add=20Docker=20documentation=20to=20the=20insta?= =?UTF-8?q?llation=20docs;=20update=20and=20create=20the=20=E2=80=9DScript?= =?UTF-8?q?s=20To=20Rule=20Them=20All=E2=80=9D=20scripts=20for=20easy=20us?= =?UTF-8?q?e=20of=20the=20Docker=20Composer=20environment.=20Fixes=20#2425?= =?UTF-8?q?.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/installation.md | 91 +++++++++++++++++++++++++++++++++------ script/bootstrap | 11 +++++ script/cibuild | 1 + script/console | 3 -- script/docker-environment | 4 +- script/setup | 18 ++++++++ script/test | 47 ++++++++++++++++++++ script/update | 13 ++++++ 8 files changed, 172 insertions(+), 16 deletions(-) create mode 100755 script/bootstrap create mode 100755 script/setup create mode 100755 script/test create mode 100755 script/update diff --git a/doc/installation.md b/doc/installation.md index d8a2a863..8310d265 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -2,11 +2,78 @@ Tracks can be installed several ways: You can run it through Docker, which is recommended because all requirements have already been taken care of for you, or you can install it on a custom server from source. -Instructions for the Docker-based installation as well as other options are available in the Tracks wiki: https://github.com/TracksApp/tracks/wiki/Installation. The wiki also has tips and instructions for specific environments. These instructions are only for installation from source in a custom environment. +Community-provided instructions for other options and tips for specific environments are available in the Tracks wiki: https://github.com/TracksApp/tracks/wiki/Installation. + +## Docker installation using Docker Compose + +You can easily run Tracks using Docker Compose. This option mounts the repository directly inside the Docker container, making it an optimal solution for developing Tracks. It does, however, also work for normal users. + +1. Make sure you have Docker Compose and Docker properly installed. +2. Get the Tracks code base by either downloading the archive file for the latest releast or cloning it from GitHub. +3. On the installation run the following command: + $ ./script/setup +4. Run the server using the following command: + $ ./script/server +5. You should now be able to access Tracks in http://localhost:3000 + +## Docker installation using a separate container + +You can also install Tracks without Docker Compose. This allows you to use the official Docker containers and you can use your existing database server instead of having a separate one for Tracks. + +*Note*: For now, you have to first build the image manually before starting the +Tracks container. In future there should be an official image in Docker Hub. You can build the image by: + +1. Get the Tracks code base by either downloading the archive file for the latest releast or cloning it from GitHub. +2. Run the following command in the Tracks directory to build the image: + $ docker build -t="tracks" . + +1. Make sure you have Docker properly installed. +2. Start a database container with either MySQL or PostgreSQL: + $ docker run -p 5432:5432 --name postgres -e POSTGRES_PASSWORD=password -d postgres + $ docker run -p 3306:3306 --name mariadb -e MYSQL_ROOT_PASSWORD=password -d mariadb +3. Create a database and a user for Tracks in the database: + # MySQL + $ mysql -u root -p + mysql> CREATE DATABASE tracks; + mysql> GRANT ALL PRIVILEGES ON tracks.* TO yourmysqluser@localhost IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION; + + # PostgreSQL + $ sudo -u postgres psql + postgres=# CREATE USER tracks WITH ENCRYPTED PASSWORD 'password-goes-here'; + postgres=# CREATE DATABASE tracks OWNER=tracks; +4. Start the Tracks container: + $ docker run -p 3000:3000 --name tracks --link mariadb:db -t tracks + $ docker run -p 3000:3000 --name tracks --link postgres:db -t tracks +5. You should now be able to access Tracks in http://localhost:3000 + +## Environmental variables in the Docker image + +You can override database connection details by defining the environment variables in the run command, for example ”-e DATABASE_USERNAME=tracks_dev” or docker-compose.yml, if using Docker Compose. + +|Name |Default |For PostgreSQL | +|------------------|-----------|---------------| +|DATABASE_NAME |tracks | | +|DATABASE_HOST |db | | +|DATABASE_PORT |3306 |5432 | +|DATABASE_USERNAME |tracks | | +|DATABASE_PASSWORD |password | | +|DATABASE_TYPE |mysql2 |postgresql | +|DATABASE_ENCODING |utf8 |unicode | +|RAILS_ENV |production | + +### Override files + +You can override files in the Docker image by using the --volume argument or docker-compose.yml, if using Docker Compose. + +|File |Argument |Replace for production?| +|-------------------|---------------------------------------------------------|-----------------------| +|config/site.yml |--volume /app/config/site.yml:/home/user/site.yml |Yes | + +## Custom server installation This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see the [upgrade documentation](upgrading.md). -## Prerequisites +### Prerequisites Tracks has a few software requirements that must be satisfied before installation: @@ -14,7 +81,7 @@ Tracks has a few software requirements that must be satisfied before installatio 2. **Bundler**. Tracks requires a recent version of [Bundler](http://bundler.io) to handle the installation of dependencies. Bundler is typically installed by running `gem install bundler`. 3. **Database**. Tracks is tested on [MySQL](http://www.mysql.com/) and [SQLite](http://www.sqlite.org/), but [PostgreSQL](http://www.postgresql.org/) can also be used. Of the three, SQLite requires the least configuration but is also the least performant and may make it difficult to operate in the future. We recommend either MySQL or PostgreSQL. Whatever your choice, the appropriate database software must be installed. -## Get Tracks +### Get Tracks There are two methods of downloading Tracks: @@ -27,26 +94,26 @@ There are two methods of downloading Tracks: git clone https://github.com/TracksApp/tracks.git cd tracks -## Set up the database +### Set up the database *This section doesn't apply if using SQLite.* You need to create a database and database-user to use with Tracks. For this, you can use an GUI tool or go into a terminal and issue the following commands: -### MySQL +#### MySQL $ mysql -u root -p mysql> CREATE DATABASE tracks; mysql> GRANT ALL PRIVILEGES ON tracks.* TO yourmysqluser@localhost \ IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION; -### PostgreSQL +#### PostgreSQL $ sudo -u postgres psql postgres=# CREATE USER tracks WITH ENCRYPTED PASSWORD 'password-goes-here'; postgres=# CREATE DATABASE tracks OWNER=tracks; -## Install dependencies +### Install dependencies Tracks is built upon a number of Ruby libraries (known as ‘gems’). The Bundler tool makes it easy to install all the gems that Tracks needs, and ensures that they are all the correct versions. @@ -74,7 +141,7 @@ Tracks is built upon a number of Ruby libraries (known as ‘gems’). The Bundl 4. If you are using Windows, you may need to check the ‘shebang’ lines (`#!/usr/bin/env ruby`) of the `/public/dispatch.*` files and all the files in the `/script` directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby` to point to the Ruby binary on your system. 5. If you intend to use Tracks behind a web server or reverse proxy with https enabled, ensure to set `force_ssl` option to `true`. -## Populate your database with the Tracks schema +### Populate your database with the Tracks schema Open a terminal and change into the root of your Tracks directory. Enter the following command: @@ -82,13 +149,13 @@ Open a terminal and change into the root of your Tracks directory. Enter the fol This will set up your database with the required structure to hold Tracks’ data. -## Precompile assets +### Precompile assets Static assets (images, stylesheets, and javascript) need to be compiled in order for them to work correctly with the new asset pipeline feature in Rails. Precompiling your assets is as simple as running the following command while inside the Tracks root directory: bundle exec rake assets:precompile RAILS_ENV=production -## Start the server +### Start the server While still in the Terminal inside the Tracks root directory, issue the following command: @@ -98,10 +165,10 @@ If all goes well, you should see some text informing you that the server is runn Optimally you should serve static files using Nginx or Apache, especially in larger production instances. If you do this, you can omit the RAILS_SERVE_STATIC_FILES=TRUE from the start of the command. -## Visit Tracks in a browser +### Visit Tracks in a browser Visit `http://localhost:3000/signup` in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit `http://yourdomain.com/mobile/`. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser. -## Customise Tracks +### Customise Tracks Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun! diff --git a/script/bootstrap b/script/bootstrap new file mode 100755 index 00000000..6d90255a --- /dev/null +++ b/script/bootstrap @@ -0,0 +1,11 @@ +#!/bin/sh + +# script/bootstrap: Resolve all dependencies that the application requires to +# run. + +set -e + +docker_compose="docker-compose --file docker-compose.yml" + +echo "==> Building Docker image…" +$docker_compose build diff --git a/script/cibuild b/script/cibuild index 52a870d6..783a1833 100755 --- a/script/cibuild +++ b/script/cibuild @@ -1,4 +1,5 @@ #!/bin/bash + set -e docker_compose="docker-compose --file docker-compose.yml" diff --git a/script/console b/script/console index ff671891..69f8d3ab 100755 --- a/script/console +++ b/script/console @@ -1,7 +1,4 @@ #!/bin/sh -appdir=$(cd $(dirname "$0")/.. && pwd) -[ -f /etc/app-env ] || exec "$appdir/script/docker-environment" $0 $@ - export RAILS_ENV='development' bin/rails console diff --git a/script/docker-environment b/script/docker-environment index d5319e06..1d51c8b1 100755 --- a/script/docker-environment +++ b/script/docker-environment @@ -2,6 +2,8 @@ set -e +docker_compose="docker-compose --file docker-compose.yml" + # Find our app dir appdir=$(cd $(dirname "$0")/.. && pwd) @@ -11,4 +13,4 @@ export VOLUME="$appdir" image=${DOCKER_IMAGE:=web} port_publish=""; [ "${BIND_DOCKER_SERVICE_PORTS:-}" = 1 ] && port_publish="--service-ports" -exec docker-compose run $port_publish --rm $image $cmd +exec $docker_compose run $port_publish --rm $image $cmd diff --git a/script/setup b/script/setup new file mode 100755 index 00000000..b9422290 --- /dev/null +++ b/script/setup @@ -0,0 +1,18 @@ +#!/bin/sh + +# script/setup: Set up application for the first time after cloning, or set it +# back to the initial first unused state. + +set -e + +docker_compose="docker-compose --file docker-compose.yml" + +script/bootstrap + +script/poll-for-db + +echo "==> Setting up DB…" +# reset database to a fresh state. +bin/rake db:create db:reset + +echo "==> App is now ready to go!" diff --git a/script/test b/script/test new file mode 100755 index 00000000..b7dc31af --- /dev/null +++ b/script/test @@ -0,0 +1,47 @@ +#!/bin/bash + +# script/test: Run test suite for application. Optionally pass in a path to an +# individual test file to run a single test. + +set -e + +docker_compose="docker-compose --file docker-compose.yml" + +function cleanup() { + $docker_compose down +} + +function die() { + echo $@ + exit 1 +} + +trap cleanup EXIT + +script/poll-for-db + +if [ "$RAILS_ENV" = "test" ] || [ "$RACK_ENV" = "test" ]; then + # if executed and the environment is already set to `test`, then we want a + # clean from scratch application. This almost always means a ci environment, + # since we set the environment to `test` directly in `script/cibuild`. + script/setup +else + # if the environment isn't set to `test`, set it to `test` and update the + # application to ensure all dependencies are met as well as any other things + # that need to be up to date, like db migrations. The environment not having + # already been set to `test` almost always means this is being called on its + # own from a `development` environment. + export RAILS_ENV="test" RACK_ENV="test" + + script/update +fi + +echo "==> Running tests…" + +if [ -n "$1" ]; then + # pass arguments to test call. This is useful for calling a single test. + $docker_compose run web bin/rake test "$1" +else + $docker_compose run web bin/rake test +fi + diff --git a/script/update b/script/update new file mode 100755 index 00000000..56dc4429 --- /dev/null +++ b/script/update @@ -0,0 +1,13 @@ +#!/bin/sh + +# script/update: Update application to run for its current checkout. + +set -e + +docker_compose="docker-compose --file docker-compose.yml" + +script/bootstrap + +echo "==> Updating db…" +# run all database migrations to ensure everything is up to date. +$docker_compose run web bin/rake db:migrate