These instructions are specifically tailored to the task of setting up a new instance of BETYdb on a CentOS 7 machine. We assume the following are installed:
Ruby Version Manager (RVM).
Apache 2.2 or greater.
PostgreSQL 9.4 or greater.
PostGIS 2.1.0 or greater.
Git 18.104.22.168 or greater.
R 3.1.0 or greater.
Graphviz dot version 2.2.1 or a version greater than 2.4.
Java 1.8 or greater.
nodejs and npm
Your preferred editor.
In addition, we assume:
You have an account on the machine, and that account has sudo access.
The PostgreSQL server is running and there is a machine user account called
postgres with password-less (peer) access to all PostgreSQL databases.
PostgreSQL has been configured so that all non-postgres database roles can
log in to the PostgreSQL server using a password, both using a UNIX domain
socket connection and using a connection to
localhost over TCP/IP.
Information about installing CentOS, adding users, installing the requisite software, and setting up and starting the PostgreSQL server is contained in various subsections below.
IMPORTANT! In what follows, we use the following placeholder names to represent names that will vary with the installation:
Operating system accounts:
<adminuser> — the operating system account name for a user with complete sudo access
<betyappuser> — the operating system account name for the user that will
own this BETY app instance; generally,
<betyappuser> should equal
<betyapp>, but we distinguish them here for clarity**
<betyapp> — the name of the parent directory of the Rails root directory for the BETY app instance
<betydb> — the name of the database this instance of the BETY app will use
<dbuser> — the owner of database
<dbpw> — the password for database user
For convenience, we generally leave off the angle brackets below as if these are the actual names that we will be using. In practice, sometimes the same name will be used for several of these; for example, often
<dbpw> will all be "bety".
This is the account we refer to as
<adminuser> above. This user will need to have sudo permissions to do such tasks as adding a new user, deploying the BETYdb code base, editing the HTTPD configuration files, and starting and restarting the Web server.
It is recommended that each Rails app be run under its own user account. Use the following command to create the user:
sudo useradd <betyappuser>
Also, you may want to ensure this user has your SSH key installed:
sudo mkdir -p ~betyappuser/.sshtouch $HOME/.ssh/authorized_keyssudo sh -c "cat $HOME/.ssh/authorized_keys >> ~betyappuser/.ssh/authorized_keys"sudo chown -R betyappuser: ~betyappuser/.sshsudo chmod 700 ~betyappuser/.sshsudo sh -c "chmod 600 ~betyappuser/.ssh/*"
In this example, we'll choose
/var/www/betyapp as the parent directory for the Rails root directory, which we'll call
sudo mkdir -p /var/www/betyappsudo chown betyappuser: /var/www/betyappcd /var/www/betyappsudo -u betyappuser -H git clone https://github.com/PecanProject/bety.git code
First cd to the Rails root directory:
If you haven't installed any versions of Ruby using the Ruby Version Manager, you should get a warning that the required version of Ruby is not installed along with the command to run to install it. Go ahead and install this version. This command should have the form
rvm install "ruby-X.X.X"
where "ruby-X.X.X" matches the contents of the file
You can use
to check that you have the correct version of Ruby installed, and
to check that you have the correct version activated.
The next several steps should be run as the app's user (
sudo -u betyappuser -H bash -lcd /var/www/betyapp/code
You may get error about not being able to create a gemset, which you may ignore, but you should check that the correct version of Ruby is active:
If the bundler fails to install the "pg" Gem, use the "bundle config" command to add an option as follows and then re-run the bundle install command:
bundle config --local build.pg --with-pg-config=/usr/pgsql-9.4/bin/pg_configbundle install
To do this from the command line, just run
cat > config/database.yml << EOFproduction:adapter: postgisencoding: utf-8reconnect: falsedatabase: <betydb>pool: 5username: <dbuser>password: <dbpw>EOF
replacing the placeholders
<dbpw> with whatever identifiers you chose to user for these entities.
The most important purpose of this file is to override the default site key so that your site will be more secure.
First, generate a secret key using the command
bundle exec rake secret
cat > config/application.yml << EOFproduction:rest_auth_site_key: '<secret key>'EOF
<secret key> is the result of the
rake secret command.
This is a minimal application configuration file. There are many other settings that may be used to customize the appearance of your site. See the sample file
config/application.yml.template for details. At the very least, it is highly recommended to set the contact information appropriate for your site.
Below, we show how to modify this file to enable the SchemaSpy documentation generator.
bundle exec rake assets:precompile RAILS_ENV=production
Important! If you are planning to deploy the BETYdb app to a sub-URI of your server name—to
yourserver.com/suburi, say, instead of
yourserver.com—then you need to set the RAILS_RELATIVE_URL_ROOT variable when precompiling:
bundle exec rake assets:precompile RAILS_ENV=production RAILS_RELATIVE_URL_ROOT=/suburi
For this first step you should still be logged in as
<betyappuser> and still be in the
curl https://raw.githubusercontent.com/PecanProject/pecan/develop/scripts/load.bety.sh > script/load.bety.shchmod +x script/load.bety.sh
Now exit the
You should now be back to the administrator account
<adminuser> that you originally logged in to.
sudo su postgres
First start psql:
Now run the
CREATE ROLE and
CREATE DATABASE commands in psql:
CREATE ROLE dbuser WITH LOGIN CREATEDB NOSUPERUSER NOCREATEROLE PASSWORD 'dbpw';CREATE DATABASE betydb WITH OWNER dbuser;\q
script/load.bety.sh -a postgres -c -d betydb -e -g -m <localdb id number> -o dbuser -r 0
<localdb id number> is some integer that is unique to each database. See [Distributed instances of BETYdb] for further information.
This will create the tables, views, indices, constraints, and functions required for BETYdb, replicating the database schema found on machine 0, the Energy Biosciences Institute server for BETYdb, whose BETYdb database schema is considered the "canonical" or "official" schema. (Other machines may have a slightly modified schema, so it is important to use the creation (
-c) option only when the remote machine is machine 0.) The tables will all be empty except for the following:
users. A guest user account ("guestuser") will be added to the users table.
This machine's database contains the most extensive metadata, so you may want load the data from this machine, not just the database schema. To do so, run the above command without the "-e" option.
script/load.bety.sh -a postgres -d betydb -m <localdb id number> -o dbuser -r <remotedb id number>
This may be executed multiple times with different remote database id numbers. Again, consult [Distributed instances of BETYdb] to see what data sources are available.
(If you used the
-e option in the previous step but then decided you want the full data from machine 0 after all, you can chose
<remotedb id number>=0.)
You should now once again be in the administrative account (
<adminuser>) and in the BETYdb app's root directory,
This should be the version listed in the file .ruby-version
passenger-config about ruby-command
Use the location given in the resulting output as the value of
path-to-ruby in the next step.
Create a new Apache configuration file (call it, say,
bety.conf) in the configuration directory
/usr/httpd/conf.d and open it in an editor. Add the following contents to the file:
ServerName yourserver.com # Tell Apache and Passenger where your app's 'public' directory is DocumentRoot /var/www/betyapp/code/public PassengerRuby /path-to-ruby # Relax Apache security settings Allow from all Options -MultiViews SetEnv SECRET_KEY_BASE # (Alternatively, put "export SECRET_KEY_BASE=" in the .bash_profile file for user.) # Uncomment this if you're on Apache >= 2.4: #Require all granted
yourserver.com with your server's host name and replace
/path-to-bety with the path found above using the
<secret key> with some long, random word. You can generate a suitable value using the command
bundle exec rake secret
(As noted in the comment, this setting can be put in the environment of
<betyappuser> instead of here in the server configuration file.)
Note: If you want your app to be served at a sub-URI of your server name, say,
yourserver.com/suburi, use the following configuration instead:
ServerName yourserver.com PassengerRuby /path-to-ruby Alias /suburi /var/www/betyapp/code/public PassengerBaseURI /suburi PassengerAppRoot /var/www/betyapp/code Allow from all Options -MultiViews SetEnv SECRET_KEY_BASE # Uncomment this if you're on Apache >= 2.4: #Require all granted
sudo apachectl restart
or, if you deployed to a suburi,
Alternatively, try visiting the URL in a browser.
In a browser, visit the home page of your new BETYdb site and click the "Register for BETYdb" button. Fill out the form; at a minimum, you must supply values for "Login", "Email", "Password", and "Confirm Password" and click the "I'm not a robot" checkbox. It is highly recommended to fill out the "Name" field as well since this is the name that will be displayed when you are logged in as the new user. Note that you cannot re-use a previously used login or e-mail address.
After completing the form, click "Sign Up". You should see the "Thanks for signing up!" message.
Once you have created a user, give that user full access privileges. To do this, use psql:
psql -U <dbuser> <betydb>
Once psql has started, if the login of the user you wish to alter is "admin", run these commands in the psql session:
UPDATE users SET access_level = 1, page_access_level = 1 WHERE login = 'admin';\q
The Guest User account password will not be set correctly unless you use 'thisisnotasecret' as the site key. But for security reasons, you shouldn't use this as a site key on a production server (which was the reason for overriding the value of
rest_auth_site_key in the customization file
config/application.yml). So you need to reset the Guest User account's password to get it to work again.
Log in to BETYdb as the administrative user you created in the previous step and go to the Users list (menu item
Data/Users). Search for "guestuser" and click the edit button for that user. Check the "change password" checkbox and then enter "guestuser" in both password fields; then click the "Update" button.
Now log out and try the "Log in as Guest" button to make sure that it works.
R to generate images for the Priors pages on the fly if they don't already exist. In order for this to work, the
R package must be installed.
To do this, start up
sudo R --vanilla
Then, inside the
R session, issue the command
This will likely take a few minutes. To check that all is well, open the BETYdb app in a browser and navigate to the Data/Priors page. The images in the middle column should start being generated on the fly.
SchemaSpy documentation is generated using Java. Two Jar files are needed, a PostgreSQL JDBC Driver file and a customized version of the SchemaSpy file. These need to be downloaded to a suitable location. By way of example, we'll put them in
/var/www/betyapp/code/lib/tasks/jar. To do this, first log in to the
sudo -u betyappuser -H bash -l
Then run the following commands:
cd /var/www/betyapp/code/lib/tasksmkdir jarcd jarwget https://www.dropbox.com/s/j50hk7cbqw7680u/schemaSpy.jarwget https://jdbc.postgresql.org/download/postgresql-42.2.4.jar
Here, we use the latest JDBC Driver file as of this writing, postgresql-42.2.4.jar.
Now, append to the
config/application.yml configuration file as follows (be sure to use
>> instead of
cat >> config/application.yml << EOFschema_spy_settings:java_executable: javapostgresql_driver_jar_file: lib/tasks/jar/postgresql-42.2.4.jarsettings_for_customized_documentation:schema_spy_jar_file: lib/tasks/jar/schemaSpy.jaroutput_directory: .remove_root_dir_files: trueEOF
rake task to generate the SchemaSpy documentation as follows:
bundle exec rake bety:dbdocs RAILS_ENV=production
Restart the Rails app with
and try visiting the database documentation in a browser by going to the URL for your running BETYdb instance and clicking the
Schema menu item under the
You should now have a fully-functional BETYdb instance.
We are not using "schema" in its PostgreSQL-specific sense, where it refers to a namespace within a database.
<VirtualHost *:80>ServerName yourserver.comRedirect permanent / https://yourserver.com</VirtualHost>
or, for suburi deployments,```<VirtualHost *:80>ServerName yourserver.comRedirect permanent /suburi https://yourserver.com/suburi</VirtualHost>```This way, the site will always be served up securely.