Revision as of 11:29, 14 September 2017

Install

Git / Github

Development is hosted on Github, so you will need a free Github account to contribute code.

If you are new to Git, you may find the Github desktop application easier to use. Alternatives are SourceTree and GitKraken.

Environment

To develop ARK requires the following tools to be installed:

• Git
• Composer
• Node.js (for frontend/theme development only)

You will also require PHP, a web server (Apache/PHP), a database server (MySQL/PostreSQL/SQLite), a web browser (Chrome/Firefox), and a an API client (Postman).

The following tools are recommend to adhere to ARK code quality standards:

• php-cs-fixer
• PHP CodeSniffer

macOS

On macOS, while you can install the requirements via standalone packages, we recommend using HomeBrew as it makes installing and updating all the tools used easier.

• Install XCode
• Install the Command Line Tools (includes Git)
• Download and install HomeBrew
• Modify your .profile to add brew packages to your $PATH

  export PATH=/usr/local/bin:/usr/local/sbin:$PATH

• Install the required packages from Brew:

  brew install homebrew/php/composer homebrew/php/php-cs-fixer homebrew/php/php-code-sniffer homebrew/php/sqlformat homebrew/php/phplint

• If you need to do front end development you will also need

  brew install node tidy-html5

• (Optional) Modify your .profile to enable command-line auto-complete

export HOMEBREW_GITHUB_API_TOKEN="token"
source /Library/Developer/CommandLineTools/usr/share/git-core/git-completion.bash
source /Library/Developer/CommandLineTools/usr/share/git-core/git-prompt.sh
GIT_PS1_SHOWDIRTYSTATE=true
PS1='\u@\h \W$(__git_ps1 " (%s)") \$ '

The easiest way to run a webserver and database server is using MAMP. Simply install MAMP and create a soft-link from the MAMP webroot to the location of your ARK git repository. The alternative is to use HomeBrew to configure and run your own install. The HomeBrew method is recommended for developing with PostgreSQL (TODO).

• brew install homebrew/php/php71 homebrew/php/php71-tidy homebrew/php/php71-xdebug

For QGIS Python:

• 'brew install python qt pyqt'
• 'pip install pep8 autopep8 jedi pb_tool '

TODO

• xdebug setup
• apache / php /mysql / mamp
• linter/fixer rulesets

Debian Stable (Stretch)

Debian Stretch ships with PHP 7.0 by default, but also enables the parallel install of other PHP versions using PHP-FM. PHP 5.6 and 7.1 are not in the official repositories, but the Debian maintainer has made them available in his repo pending their being pushed to Debian Backports. LP Archaeology use this combination for our servers and we strongly recommend you use this method for both simplicity and reliability.

Instructions for NodeJS: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions

Instructions for PHP 7.1: https://packages.sury.org/php/README.txt. See also https://github.com/oerdnj/deb.sury.org/wiki/Managing-Multiple-Versions

Summary of install commands

sudo apt-get install build-essential git apache2 mariadb-client mariadb-server \
php7.1 php7.1-bcmath php7.1-bz2 php7.1-cli php7.1-common php7.1-enchant php7.1-fpm php7.1-gd php7.1-intl \
php7.1-json php7.1-mbstring php7.1-mcrypt php7.1-mysql php7.1-opcache php7.1-readline php7.1-sqlite3 \
php7.1-tidy php7.1-xml php7.1-zip phpmyadmin php-apcu php-apcu-bc php-geoip php-getid3 php-imagick \
php-pear libphp-phpmailer php-php-gettext php-phpseclib php-tcpdf php-uuid php-yaml 

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

curl -sS https://getcomposer.org/installer -o composer-setup.php
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Enabled FPM

sudo service php7.1-fpm start
sudo systemctl enable  php7.1-fpm
sudo a2enconf php7.1-fpm
sudo a2enmod proxy_fcgi rewrite

Once ARK is installed (see below), configure Apache to serve the site, using either alias or symlink.

sudo vim /etc/apache2/sites-available/dime.conf

 <VirtualHost *:80>
     ServerName dime2.lparchaeology.com
     ServerAdmin sysadmin@lparchaeology.com
     DocumentRoot /srv/www/lib/ark2/sites/dime/web
     DirectoryIndex index.html index.php
     LogLevel warn
     ErrorLog /srv/www/lib/ark2/sites/dime/web/var/logs/error.log
     CustomLog /srv/www/lib/ark2/sites/dime/web/var/logs/access.log combined
     <Directory "/srv/www/lib/ark2/sites/dime/web">
         Options FollowSymLinks
         Require all granted
         AllowOverride None
         AcceptPathInfo On
         RewriteEngine On
         RewriteCond %{REQUEST_FILENAME} !-f
         RewriteRule ^(.*)$ /index.php [QSA,L]
    </Directory>
 </VirtualHost>

sudo a2ensite dime

systemctl reload apache2

Install

To install using git:

mkdir /srv/www/lib
cd /srv/www/lib
git clone https://github.com/lparchaeology/ark2.git

Alternatively download and unzip the file from https://github.com/lparchaeology/ark2

Then run composer to install the required PHP libraries:

cd ark2/
composer install
<may need github token...>

Run the Sysadmin console to check your install:

./bin/sysadmin
./bin/sysadmin system:about

Check the database server config file is correct for your install:

less sites/servers.json

If you need to add different server details:

./bin/sysadmin database:server:add

To create a new site:

./bin/sysadmin site:create <site>
./sites/<site>/bin/console

Now edit the site config files to reflect your site settings. Most settings will have the correct default, but some may need tweaking:

vim sites/<site>/config/site.json

If not using vhosts, for local development you can symlink the site

cd ..
ln -s sites/<site>/web  /Applications/MAMP/htdocs/<site>
http://localhost:8888/<site>

To rebuild the frontend

cd build
./build env:install
./build frontend:all <frontend>