mirror/osem
1
0
Fork 0
mirror of https://github.com/openSUSE/osem.git synced 2026-05-25 00:50:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

Fixup INSTALL.md

Browse Source 
- add a big fat warning
- Do not mentioned the deprecated docker setup anymore
- Fixup docker-compose production setup
This commit is contained in:
Henne Vogelsang
2019-01-30 01:35:01 +01:00
parent 9b97ecdb58
commit 2a7acf7369
4 changed files with 78 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
Dockerfile.production
View File

@@ -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

140
INSTALL.md
View File

@@ -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:
<a href="https://heroku.com/deploy?template=https://github.com/openSUSE/osem/tree/v1.0">
<img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
</a>
### 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.

35
docker-compose.yml.production-example
View File

@@ -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:

11
lib/tasks/db.rake
View File

@@ -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