From 2a7acf73690b00cbbedefb65e3cc5d7dad77cadc Mon Sep 17 00:00:00 2001 From: Henne Vogelsang Date: Wed, 30 Jan 2019 01:35:01 +0100 Subject: [PATCH] Fixup INSTALL.md - add a big fat warning - Do not mentioned the deprecated docker setup anymore - Fixup docker-compose production setup --- Dockerfile.production | 15 +-- INSTALL.md | 140 ++++++++++---------------- docker-compose.yml.production-example | 35 ++++--- lib/tasks/db.rake | 11 +- 4 files changed, 78 insertions(+), 123 deletions(-) diff --git a/Dockerfile.production b/Dockerfile.production index 75b3dfc7..12582dd9 100644 --- a/Dockerfile.production +++ b/Dockerfile.production @@ -1,23 +1,16 @@ FROM osem/base -# We copy the Gemfiles into this intermediate build stage so it's checksum -# changes and all the subsequent stages (a.k.a. the bundle install call below) -# have to be rebuild. Otherwise, after the first build of this image, -# docker would use it's cache for this and the following stages. -COPY Gemfile /osem/ -COPY Gemfile.lock /osem/ -RUN chown -R osem /osem - # Add our files +COPY --chown=1000:1000 . /osem/ + USER osem WORKDIR /osem/ -COPY --chown=osem:osem . /osem/ # Install our bundle RUN export NOKOGIRI_USE_SYSTEM_LIBRARIES=1; bundle install --jobs=3 --retry=3 --without test development -# Configure OSEM -RUN mv config/database.yml.example config/database.yml +# Generate assets +RUN export RAILS_ENV=production; bundle exec rake assets:clobber assets:precompile ENV RAILS_ENV=production diff --git a/INSTALL.md b/INSTALL.md index 52741ad9..c9279bbb 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,110 +1,72 @@ # Install Open Source Event Manager -All the information that you need to install OSEM. If you have any problems with installing don't hesitate to [contact us](https://github.com/openSUSE/osem#contact) +Here is what you need to install OSEM. -## Versions -OSEM is an [semantic versioned](http://semver.org/) app. That means given a version number MAJOR.MINOR.PATCH we increment the: +# 💥💥💥 WARNING 💥💥💥 +![explosions](https://media.giphy.com/media/Yl5aO3gdVfsQ0/giphy.gif) -1. MAJOR version when we make incompatible changes, -2. MINOR version when we add functionality in a backwards-compatible manner -3. PATCH version when we make backwards-compatible bug fixes +OSEM is a Ruby on Rails server application for professional use, not some desktop app you run for yourself. If you deploy it, **YOU** are responsible for the data that users enter into it, this data includes personal information like email addresses and/or passwords that most likely can be used to harm them in some form (cracking, doxing, social engineering). -## Download -You can find the latest OSEM releases on our [release page](https://github.com/openSUSE/osem/releases/latest) ([older release here](https://github.com/openSUSE/osem/releases)) +If you never deployed a Ruby on Rails app before we **strongly** suggest you seek help from someone who has. That someone is **NOT** the OSEM team so please do **NOT** open an issue expecting us to explain how to do this. +*You should know what you do and you have been warned*. -## Deploy - -OSEM is a *Ruby on Rails* application. We recommend to run OSEM in production with [mod_passenger](https://www.phusionpassenger.com/download/#open_source) -and the [apache web-server](https://www.apache.org/). There are tons of guides on how to deploy rails apps on various -base operating systems. [Check Google](https://encrypted.google.com/search?hl=en&q=ruby%20on%20rails%20apache%20passenger) ;-) - -For more information about rails and what it can do, see the [rails guides.](http://guides.rubyonrails.org/getting_started.html) - -If you have an heroku account you can also +## Deploy to the cloud +The easiest way to deploy OSEM is to use one of the many platform as a service providers that support ruby on rails. We have prepared OSEM to be used with [heroku](https://heroku.com). So if you have an account there, you can deploy OSEM by pressing this button: Deploy -### Deploy with Docker +## Deploy to your own server +We recommend to run OSEM in production with [mod_passenger](https://www.phusionpassenger.com/download/#open_source) +and the [apache web-server](https://www.apache.org/). There are tons of guides on how to deploy rails apps on various +base operating systems. [Check Google](https://encrypted.google.com/search?hl=en&q=ruby%20on%20rails%20apache%20passenger). Of course there are also other options for the application server and reverse proxy, pick your poison. -You can deploy OSEM using [Docker](https://docker.com/) and [Docker-Compose](https://docs.docker.com/compose/overview/). - -*This is just a short guide and does not explain how to use Docker and/or Docker-Compose. You need some experience with these tools to be able to deploy OSEM with Docker properly.* - -First of all, copy `docker-compose.yml.example` to `docker-compose.yml` and `docker-compose.env.example` to `docker-compose.env`. You should immediately change -`docker-compose.env`'s permissions to `0600` to make sure all the passphrases in it are kept secret. -(Tip: the easiest and most secure way to do it is to do it with a single command, for example `install -m 0600 docker-compose.env.example docker-compose.env`). - -There are two configurations to deploy OSEM with Docker: *evaluation mode* and *production mode*. - -#### Evaluation mode - -If you want to evaluate OSEM to see if it fits your needs, the default configuration in `docker-compose.env` will work perfectly fine for you. -For convenience reasons, `docker-compose.yml` already contains a [MailHog](https://github.com/mailhog/MailHog) service configuration. MailHog -is going to catch every email sent by OSEM and displays them on a special web service. Thus, it eliminates the need to set up an SMTP server just to try out OSEM. -Just point your browser to http://localhost:8025 to get access to registration confirmation links etc. - -Run `docker-compose up --build` to start the services. On first run, it will take a few minutes to initialize the database. Thus, wait a few minutes before you open up -http://localhost:9292 in your browser. - -#### Production mode - -To deploy OSEM for production, you have to make a few changes to `docker-compose.yml`. First, remove (or comment) the `mailhog` service, as it is only useful for evaluation and -cannot be used for production. -You can change the forwarded port from port `9292` to any other value if this port is already in use or you just want to use another one. - -Next, you have to modify `docker-compose.env`. This file works as a Docker-like replacement for the regular Rails `.env` files described below. -You can configure any of the configuration values shown in the **Configure** section below in it. The most essential variables are already configured to standard -values in `docker-compose.env` which you most likely want to change. - -First, you need to modify the email related settings. You need a working SMTP server for OSEM to send out registration confirmation mails etc. - -For security reasons, the following variables have to be changed, too: - - - `MYSQL_PASSWORD` - - `MYSQL_ROOT_PASSWORD` - - `SECRET_KEY_BASE` - -These variables need to be set to the correct values at first, as they are used to initialize everything. Modification of these variables after installation and initialization is more -complicated and out of this document's scope. - -As with any other Docker-Compose configuration, run `docker-compose up --build` (or `docker-compose up --build -d` to run in background) to start the services. During the first -start, the database has to be initialized which can take several minutes. The web service is by default exposed on localhost only as it is intended to be served by a reverse proxy (for SSL -termination, caching etc.). -You should not directly expose the web server port unless you have a good reason to do so. +## Deploy via docker/docker-compose +There is a rudimentary docker-compose configuration for production usage (`docker-compose.yml.production-example`). It brings [OSEM up](http://0.0.0.0:8080) on port 8080. It uses persistent storage volumes for all the data users might create. You can start it with -## Configure -There are a couple of environment variables you can set to configure OSEM. Check out the *dotenv.example* file. +1. Configure OSEM + You have at least to set `SECRET_KEY_BASE` + ``` + cp dotenv.example .env.production + vim .env.production + ``` +1. Build the docker image (only once) + ``` + docker-compose -f docker-compose.yml.production-example build + ``` +1. Start the services + ``` + docker-compose -f docker-compose.yml.production-example up + ``` -### Online Ticket Payments -We use [Stripe](https://stripe.com) for accepting your ticket payments securely over the web. -Our application uses iFrame for accepting your user's payment details without storing them, making the application PCI SAQ-A Compliant. -Please refer to [PAYMENTS](PAYMENTS.md) documentation file for setting up your stripe account and start accepting payments from your users. +## Configuration +OSEM is configured through environment variables and falls back to sensible defaults. See the [dotenv.example](https://github.com/openSUSE/osem/blob/master/dotenv.example) for all possible configuration options. However here is a list of things you most likey want to configure because otherwise things will not work as expected. -## Dependencies +### `SECRET_KEY_BASE` +A [random string](https://www.randomlists.com/string?base=16&length=64&qty=1) to encrypt sessions/cookies. -### ImageMagick -We use [ImageMagick](http://imagemagick.org/) for image manipulation so it needs to be available in your installation. -If you would like to resize exisiting logos in your OSEM installation you can do so by running the following rake task: +### `OSEM_NAME` +The name of your OSEM installation -```shell -$ bundle exec rake logo:reprocess -``` -### Ruby -OSEM is using Ruby version 2.5 +### How to send emails +By default OSEM tries to send emails over localhost. -## openID -In order to use [openID](http://openid.net/) logins for your OSEM installation you need to register your application with the providers ([Google](https://code.google.com/apis/console#:access), [GitHub](https://github.com/settings/applications/new) or [Facebook](https://developers.facebook.com/)) and enter their API keys in the environment variables found in your *.env* file(s). +#### `OSEM_HOSTNAME` +The host this OSEM instance runs on. This is used for generating urls in emails sent. -## Recurring Jobs -Open a separate terminal and go into the directory where the rails app is present, and type the following to start the delayed_jobs worker for sending email notifications. -``` -bundle exec rake jobs:work -``` +#### `OSEM_EMAIL_ADDRESS` +The address OSEM uses to sending mails from. -## Performance -If you are experiencing performance issues (or just curious), you may be able to [apply a free Skylight account](https://www.skylight.io/oss). -Once you have your account setup, simply set `SKYLIGHT_AUTHENTICATION` and `SKYLIGHT_PUBLIC_DASHBOARD_URL` in your `.env` file. -If you are reporting a performance issue or submiting a performance patch, it would be helpful (but not required) to link to the relevant Skylight data. +#### `OSEM_SMTP_ADDRESS` +The mail server we send mail over. (*default*: localhost) + +#### `OSEM_SMTP_AUTHENTICATION` +If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of :plain (will send the password in the clear), :login (will send password Base64 encoded) or :cram_md5 (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information) + +#### `OSEM_SMTP_USERNAME` +If your mail server requires authentication, set the username in this setting. + +#### `OSEM_SMTP_PASSWORD` +If your mail server requires authentication, set the password in this setting. diff --git a/docker-compose.yml.production-example b/docker-compose.yml.production-example index e15206d8..73fa1ad1 100644 --- a/docker-compose.yml.production-example +++ b/docker-compose.yml.production-example @@ -1,29 +1,32 @@ version: "2" services: - database: + production_database: image: postgres environment: PGDATA: /var/lib/postgresql/data/pgdata volumes: - - database:/var/lib/postgresql/data/pgdata - osem: - build: . - dockerfile: Dockerfile.production - env_file: .env.production # see dotenv.example file + - osem_production_database:/var/lib/postgresql/data/pgdata + production_web: + build: + context: . + dockerfile: Dockerfile.production depends_on: - - database + - production_database ports: - - 3000:3000 + - 8080:3000 + env_file: .env.production # see dotenv.example file + environment: + OSEM_DB_HOST: production_database + command: /osem/bin/osem-init.sh volumes: - - .:/osem - - web-data:/osem/public/system - - web-assets:/osem/public/assets - - web-logs:/osem/log + - osem_production_web_data:/osem/public/system + - osem_production_web_assets:/osem/public/assets + - osem_production_web_logs:/osem/log # named volumes to persist data volumes: - database: - web-data: - web-assets: - web-logs: + osem_production_database: + osem_production_web_data: + osem_production_web_assets: + osem_production_web_logs: diff --git a/lib/tasks/db.rake b/lib/tasks/db.rake index 89299227..8e5c382f 100644 --- a/lib/tasks/db.rake +++ b/lib/tasks/db.rake @@ -3,16 +3,13 @@ namespace :db do desc 'Bootstrap the database for the current RAILS_ENV (create, setup & seed if the database does not exist)' task bootstrap: :environment do - puts 'Bootstrapping the database...' - begin - # Only do this if the database does not exist... - Rake::Task['db:version'].invoke - # rubocop:disable Style/RescueStandardError - rescue - # rubocop:enable Style/RescueStandardError + if ActiveRecord::Base.connection.tables.empty? + puts 'Bootstrapping the database...' Rake::Task['db:create'].invoke Rake::Task['db:setup'].invoke Rake::Task['db:seed'].invoke + else + puts 'Database exists, skipping bootstrap...' end end end