Getting started
These instructions cover the installation and configuration of Facade on Debian Stretch, but should work for any other recent Debian-based distribution (Ubuntu 17.10+, etc).
Facade is designed to be run directly from a directory in your webserver. All of the control files and the cloned git repos will be in here, unless you configure it to store them elsewhere.
This guide will walk you through the basic setup, from clone to cron. To make things cleaner and to avoid collisions with other websites you may be running, it assumes you will set up a separate webroot for Facade. This also allows Facade to run as a regular user.
In your home directory, clone the code:
$ git clone https://github.com/brianwarner/facade
Navigate to the utilities directory, and run the script to install dependencies. You can either install the full version of Facade (installs Apache and PHP for the web UI), or install the minimal version (no Apache or PHP, just the basics needed to configure the system and run an analysis using the CLI). In this case, we will assume most people want the full install:
$ cd ~/facade/utilities
$ ./install_deps-full.sh
Now it's time to set up the database. Assuming you have your root MySQL password, this will be easy because Facade will create everything you need. If you don't, ask your MySQL admin to create a database for you, and make sure it uses utf8mb4 for the character set and collation.
$ cd ~/facade/utilities
$ ./setup.py
Select 'c' and 'yes' to create the config files. You need these even if you already have a database. Then follow the prompts to either add your own credentials, or to use randomly generated ones.
It will ask you if you want to use a separate database to store the alias and affiliation data. Most of the time your answer will be 'no', unless you plan to run multiple instances of Facade and want them to share the email->domain mappings. In this scenario, you'll answer 'yes' and enter the same credentials each time.
Next it will ask you about creating tables, so answer 'yes'. If you're sharing an alias and affiliations database, it'll ask you if you want to keep the existing data. You will always answer 'keep' here, unless you have a good reason to wipe this information out.
After setup.py completes, you should be see custom instructions for how to set up Apache.
Note: Skip down to the cron instructions if you installed with minimal dependencies. You will use cli/facade.py instead.
You can probably use the instructions generated by setup.py, but in case you want to do it manually, you can follow these generic steps instead.
First edit the main apache2.conf:
$ sudo vim /etc/apache2/
Now add the following, where user is replaced by your username
<Directory /home/user/facade/web/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
Note that if you are editing the default entry (e.g. on Ubuntu), you may need to change "AllowOverride" from "None" to "All" or your Facade instance menu links will be broken.
Next, create the Facade site:
$ cd /etc/apache2/sites-available
$ sudo cp 000-default.conf facade.conf
And tweak the Facade site configuration:
$ sudo vim facade.conf
Change the DocumentRoot to match where you cloned the Facade files:
DocumentRoot /home/user/facade/web/
Now, disable the default site, enable the facade site and some important modules, and restart Apache:
$ sudo a2dissite 000-default.conf
$ sudo a2ensite facade
$ sudo a2enmod rewrite
$ service apache2 reload
If you're doing this on your own machine, you should be able to visit http://localhost and see Facade.
At the bottom of the page, click 'manage' and log in.
Click Projects, and add a new project. For example, "Facade".
Now click on the project, and choose "Add a single repo". Paste the URL to the git repo, in this case https://github.com/brianwarner/facade
On the command line, run the worker script that clones the repo, analyzes it, and produces the summary:
$ cd ~/facade/utilities
$ ./facade-worker.py
When facade-worker.py completes, you will see the summary statistics on the project page. You're done! Well, mostly...
If you see (Unknown) affiliations, you can go to the "People" page and add mappings that tell Facade what domains go along with which company names. After you've done this, you'll need to re-run facade-worker.py to see the changes.
Facade is intended to be run on a regular basis, so that you never have to wait for current statistics. The best way to do this is to setup a cron job.
$ crontab -e
You can run your cron job as often as you like, and Facade will generally do the right thing. On the configuration page you can set the time between repo updates. If Facade runs sooner than this time, it'll just ignore the repo until the time has expired. The more often you run Facade, the faster it will process new repositories.
Add this line to run it hourly (for example). Replace "user" with your username:
0 * * * * /usr/bin/python3 /home/user/facade/utilities/facade-worker.py
The main way you can tell something went wrong is if analysis takes much longer than expected. The first analysis will always be long, because Facade has to clone the repos and crunch through all of the historical commits. This can take a long time, particularly for big projects like the kernel. Subsequent analyses will always be faster, because Facade will only scrape the new commits since the last analysis.
If you halt facade-worker.py, you will need to reset its status before it will run again. This prevents it from running too often and tripping over itself.
$ cd ~/facade/utilities
$ ./reset-status.py
If you think something is wrong, try turning on more verbose logging on the Configuration page, and run facade-worker.py from the command line. Unless you see an explicit error, it's probably just a really long analysis.