Skip to content

Latest commit

 

History

History
203 lines (138 loc) · 7.37 KB

INSTALL.md

File metadata and controls

203 lines (138 loc) · 7.37 KB
Raw

Installation of BW-Rox

  1. Clone via Git:

    $ git clone https://github.com/BeWelcome/rox.git

    For a first look around a read-only clone will do. If you want to support development please fork the repository and send pull requests.

  2. You can choose to install using A) Docker and Docker Compose or B) Installation step by step of BW-Rox (GNU/Linux) (see below)

A) Install using Docker and Docker Compose

The docker configuration is still in-progress, and is currently missing the setup of the sphinx search functionality (essential for using all of the search functionality in the app). Until configuration is complete, local installation is recommended.

Requirements

  • Docker
  • Docker Compose
  • If running on Windows, we recommend installing WSL in order to execute the following linux commands. Note that the files of the repository should be put into the WSL file share and not below your user directory or someplace else easily accessible by Windows.

Initialize installation

  1. Install using Docker and Docker Compose:

    $ make install

    If you need to run Docker Compose as sudo, run the following:

    $ make install root=1
    Troubleshooting

    Windows users may run into a build error concerning composer clear-cache. If you see this error, please try the following: * If you receive the error when running make install, try running make install root=1. Make sure to run the command with root=1 after trying each of the following steps as well * Ensure that you are using WSL version 2 for your linux distro (how to upgrade from WSL 1 to WSL 2) * Use Ubuntu 22.04 LTS as your linux distro - the error has been observed on earlier versions of Ubuntu, e.g. on 18.04 LTS

Wait a few minutes for containers to build and start (it might take awhile). Project is running at http://localhost:8080. If you see a "502 Bad Gateway" error in your browser, the app is still being built, and should serve the page without error once all processes finish.

  1. If you want to import geonames data, run the following (this operation takes awhile!):

    $ make install-geonames

    Once again, if you need to run Docker Compose as sudo, run the following:

    $ make install-geonames root=1

Please read Useful hints section below.

B) Installation step by step of BW-Rox (GNU/Linux)

These steps have been tested on Debian/Ubuntu based systems. Commands, usernames and locations might differ on your distribution.

Windows users may use XAMPP and execute most of the commands in the git bash. Commands for mysql need to be run in the XAMPP shell. Instead of wget either download using a browser or use curl url > filename.

Requirements

  • Apache with mod_rewrite enabled
  • PHP version >= 7.4 < 8.0
  • PHP GD lib enabled
  • PHP extensions: mbstring, xml, fileinfo, intl, xsl, xmlrpc (see composer.json)
    • note that the xml extension does not need to be installed on Windows as it is installed by default
  • MariaDB >=10.1
  • symfony command line interface (download/setup)
  • SMTP server for email features
  • Composer Version 2 (installed globally)
  • Node.js Latest version (installed globally)
  • Yarn Latest version
  • Sphinxsearch Version 3
  • wget (if you want to follow the instructions word to word) otherwise curl and the -o parameter should be your friend

Initialize installation

  1. Install the rox dependencies using composer and yarn

    $ composer install
$ yarn install --frozen-lock

  2. Initialize the database.

    Copy .env into a .env.local file and edit the DB_HOST to point to localhost (assuming MariaDB runs locally).

    In mysql create a new global user bewelcome with password bewelcome.

    This generates a new database as given in the .env.local file and presets some data.

    $ php bin/console test:database:create --drop --force

Test and log in

  1. Run

     $ make build version

    to build the CSS and JS files. The version creates a file referenced in the footer.

  2. Build sphinx indices and run search daemon

    Adapt setup/sphinx/sphinx-3.conf to match your needs: update DB credentials and replace all occurences of with the path to your sphinx indexes folder (or other folder of your preference), e.g. C:/Program Files/Sphinx/sphinxdata/indexes

    Run the indexer to create indices:

    $ indexer --config indices-3.conf --all

    Serve the indices using the search daemon:

    $ searchd --config indices-3.conf

  3. Start the server

     $ symfony serve

    Access the site using http://localhost:8000/ or with https://localhost:8000/ (if you installed certificate for symfony)

Please read Useful hints section below.

  1. (Optional) Load languages and translations

    $ wget https://downloads.bewelcome.org/for_developers/rox_test_db/languages.sql.bz2
$ wget https://downloads.bewelcome.org/for_developers/rox_test_db/words.sql.bz2
$ bunzip2 languages.sql.bz2 words.sql.bz2
$ mysql bewelcome -u bewelcome -pbewelcome < languages.sql
$ mysql bewelcome -u bewelcome -pbewelcome < words.sql

  2. (Optional) Load geonames database (this operation takes awhile!)

    $ wget http://download.geonames.org/export/dump/allCountries.zip > docker/db/allCountries.zip
$ wget http://download.geonames.org/export/dump/alternateNames.zip > docker/db/alternateNames.zip
$ wget http://download.geonames.org/export/dump/countryInfo.txt > docker/db/countryInfo.txt
$ unzip docker/db/allCountries.zip -d docker/db/
$ unzip docker/db/alternateNames.zip -d docker/db/
$ rm docker/db/*.zip
$ mysql bewelcome -u bewelcome -pbewelcome < import.sql

    After this you should rebuilt the indices for sphinx:

    $ /usr/bin/indexer --config indices-3.conf --rotate --quiet --all

Useful hints

  • Log in as user member-2 and password password. There is also a user bwadmin which has some rights assigned (and uses the same password).

  • Click around the site a bit and check if all CSS and images are loaded. Refer to var/log/dev.log if errors appear or something looks broken. Also make use of the Symfony debug toolbar.

  • Geographical data (without optional geonames database):

    There are exactly two cities in the dump: Berlin and Jayapura.

  • Resetting all user passwords:

    $ mysql bewelcome -u bewelcome -pbewelcome
    mysql> UPDATE members SET password = PASSWORD('password');
mysql> exit;

  • When doing bigger updates clear the cache from time to time with

    $ php bin/console cache:clear

  • Production OS is Debian GNU/Linux Strech.

Create documentation

If you need documentation check out MKDocs.