Setup - Retrospring/retrospring GitHub Wiki

[!WARNING] This guide is outdated, please read the new documentation on self-hosting Retrospring here!

This page will cover general setup steps for your own local/production running Retrospring instance!

Requirements

  • UNIX-like system (Linux, FreeBSD, ...)
  • Ruby 2.7.0+
  • Node 12+
  • Bundler
  • PostgreSQL
  • Redis (for Sidekiq)
  • ImageMagick (for image processing)

Installation

Development

Docker

  • Install Docker for your platform of choice
  • Follow the steps outlined in Setup/General
    • Configure your database using the environment variables given in docker-compose.yml
  • Build the Docker image for Retrospring and start up the required containers
    docker-compose up -d --build

Retrospring should be running on localhost:3000. You can access the container running the application using docker-compose exec web bash, this is where you need to run bundle exec rails * commands or interact with Rails from the command line in general

Note: If you are running Docker on WSL make sure you also clone Retrospring into a WSL mount to fully utilize the performance benefits of the subsystem

Mac OS

  • Install Homebrew
  • Run brew bundle in this project's directory to install all dependencies.
  • Install yarn using npm: npm install yarn
  • Follow the steps outlined in Setup

If you do not wish to install Node or wish to install it by means other than Homebrew, use HOMEBREW_BUNDLE_BREW_SKIP=node brew bundle

Production

We've installed Retrospring on FreeBSD 10 using rvm. What we also did was creating a new, seperate user just for justask to run in. On FreeBSD, this is done with:

# pw user add justask

Database

At Retrospring, we were using PostgreSQL as the database backend. The software might work on MySQL too, but that was not tested.

Installation from Ports (using portmaster):

# portmaster databases/postgresql93-server
PostgreSQL
$ sudo -u postgres psql -d template1
template1=# CREATE USER justask CREATEDB;
template1=# CREATE DATABASE justask_production OWNER justask;
template1=# \q

Try connecting to the database:

$ psql -U justask -d justask_production

Web Server

You'll need a web server that acts as a reverse proxy to Retrospring.

Nginx

See docs/nginx.conf for the configuration we use on Retrospring.

Setup

General

  • Clone the repository
    git clone https://github.com/Retrospring/retrospring.git
  • Configure Retrospring
    • Copy config/justask.yml.example to config/justask.yml and edit its contents
    • Copy config/database.yml.example to config/database.yml and edit its contents

Development

Install Dependencies

// Ruby
$ bundle install --without production mysql

// Node
$ yarn install

Export language files

$ bundle exec i18n export

Initialize Database

$ bundle exec rake db:prepare RAILS_ENV=development

Compile Assets

$ yarn run build
$ yarn run build:css

Run Application

$ bundle exec rails server

Production

Install Dependencies

// Ruby
$ bundle install --deployment --without development test mysql

// Node
$ yarn install --frozen-lockfile

Export language files

$ bundle exec i18n export

Initialize Database

$ bundle exec rake db:migrate RAILS_ENV=production

Precompile Assets

$ bundle exec rake assets:precompile RAILS_ENV=production

Run Application

$ foreman start

First Steps

Now visit your newly created instance at localhost:3000 or the configured hostname and register a new account.

Administrator

To give yourself administrator permissions there's two supported ways:

Rake

$ bundle exec rake 'justask:admin[your_username]' RAILS_ENV=...

your_username being your username and RAILS_ENV being set to either development or production

You can find more rake tasks to use here!

Rails Console

$ bundle exec rails c RAILS_ENV=...
> @user = User.first
> @user.add_role :administrator
> @user.save!