Installation

Steps

If you are using Windows, try and install Docker , but be warned that it may not work, in which case follow the instructions for Windows below. Only some versions of Windows let you run Docker and it may also require a BIOS change.

The docker image for the system takes up >800Mb. If you are short of disc space then you might want to try the other kind of installation.

1. Install Docker on your system.
2. Create a directory with a suitable name and cd into it.

3. Run the command:

   docker run -d -p 80:80 -v PATH-TO-DIRECTORY/www:/var/www/html -v PATH-TO-DIRECTORY/db:/var/lib/mysql rivets/framework2

   where PATH-TO-DIRECTORY is the full path name of your current directory. (If you are in a UNIX shell then you can most likely use $(pwd) or $PWD to substitute this value, but not all shells support this)

   You need to make sure that you don't have any other web server running on port 80 when you run this command or the run will fail. Some macOS installations run a web server by default and this needs to be stopped – see the notes for installation on macOS.

4. The Docker run should have created two directories : db and www in your current directory. The db directory contains the database for your site and you should not need to touch it. The www directory contains all the source code and this is where you will be building your system. Note that this has command has started a background process that will continue to run — see below for how to terminate the process.
5. Using your browser go to http://localhost/install.php and fill in the installation form. The database name, username and password for the database are all "framework". These have already been set up for you and you do not need to change them. (If for some reason you do want to change these then you need to start a docker shell (see below) and use mysql to alter the values.)

Now, got to http://localhost/admin/ or use the link on the successful installation page.

Trouble Shooting

Speak to Lindsay.....

Useful docker commands

Note, you can execute several commands from the Docker GUI dashboard which is much easier than using the command line!

docker ps

This lists all your currently running docker containers

docker stop

This stops a container, but you have to identify the container using the long id shown in the docker ps output. A useful shortcut in UNIX shells is :

docker stop `docker ps -q`

This stops all your containers.

Clean up storage

Docker stores lots of files. You might want to clean them up. This removes all stoped containers.

docker container prune

If you want to remove all the Docker images then you can use:

docker rmi `docker images -q`

Running a shell in the Framework container

Sometimes it is useful to be able to run a shell in the docker container. You can do this by slightly altering your normal run command:

docker run -it -p 80:80 -v PATH-TO-DIRECTORY/www:/var/www/html -v PATH-TO-DIRECTORY/db:/var/lib/mysql rivets/framework2 /bin/bash

where PATH-TO-DIRECTORY is the full path name of your the directory as above (or use $(pwd) )This will give you a root shell prompt on your terminal for the container.

Steps

Throughout this webproject is a placeholder for whatever you decide to call the directory in which you are installing the Framework!

1. If you have not already done so, install a LAMP stack on your machine. Make sure you have the latest version of Apache (2.4.x), PHP of at least version 7.1, and mysql or mariadb at least version 5.5. Make sure that you also have git installed on your machine and that you have the right public keys to allow you to access github.

   Make sure that your search PATH is set so that when you run php you get the version you installed. Type php -v to find out which version you are seeing.

   Ubuntu users may find this site useful.

2. Make sure the Apache web server is running.
3. Change directory to the root of your web server, this will usually be called "htdocs". (Typically /opt/httpd/htdocs).

4. You can fork your own copy of the framework or clone it from git using the command

   git clone https://github.com/rivets/framework2.git webproject

   Make sure you replace "webproject" with whatever you would like to call your project directory.

   If you have problems cloning the repository you can download the zip file from github and unzip it. Then rename the directory to whatever you have chosen for your project.

   Note that you will not be able to use git pull to get updates to the framework if you do this so cloning is much the best way forward..

5. Now cd into the directory you cloned the framework into and run ./scripts/firstrun.sh. This will set up necessary permissions and run composer. If composer is not available it will fetch a copy.

6. Now you need to create a MySQL database for your application. How you do this depends on your installation. You might have access via phpmyadmin to the database for your server, you may have to use command line access or you may have a GUI program that gives you access. Create an empty database with an appropriate name and then create a user and grant access to the database for that user on localhost. Do the equivalent of the sql commands:

   
   CREATE DATABASE webproject;
   GRANT ALL ON webproject.* TO username@localhost IDENTIFIED BY 'password';
                   

   Of course, you need to remember the username and password for subsequent steps…

7. If you have run the ./scripts/firstrun.sh script successfully, the next steps should have been done for you so you can skip them. If for some reason they have not worked, the installer will tell you about any problems when you run it, and you can follow the steps laid out here.

   In order to run the web based installer you need to set some access permissions so that the web server can create files for you.

   On a Linux LAMP stack system it is likely that the web server will be running with a low privilege user id (nobody, daemon or similar) and so you will need to change some permissions before it can create files. (Note that if you want your web system to be able to upload files, you will need to carry out similar permission wrangling for the upload directory.) The Apache configuration file for the system should tell you the values for the user and group that the server uses when running. If you really can't find out then you can run Apache and use the top or ps commands to see who owns the running httpd process.

   The installer needs to be able to create files and directories in various places in the webproject directory so it needs to have extra write permissions. The distribution also comes with a .htaccess file that directs all access to the installer, and the installer needs to be able to overwrite this file to setup the proper rules. You may have to be superuser or be using sudo to execute some of these commands.

   • You can change the owner or group for the directories (webproject and webproject/class/config) to be the same as the values used by the web server. This will require superuser permission. If you change only the group then you may have to give group write permission on the directories as well.

     chmod g+w webproject webproject/class/config webproject/.htaccess webproject/assets

   • The simplest, but least secure way is simply to give write access on the directories and .htaccess to everyone:

     chmod og+w webproject webproject/class/config webproject/.htaccess webproject/assets

     If you do this, be sure to change these back when the installer has run successfully!

     chmod og-w webproject webproject/class webproject/.htaccess webproject/assets

8. Now, in your browser, go to the URL http://localhost/webproject/install.php – substituting the correct directory name – and fill in the form that you see there (and remembering the database access username/password combination from above).

Post-install Clean up

Run the scripts/afterinstall.sh script.

When the installation has finished successfully, and you are absolutely sure that you are not going to have to reinstall, run the ./scripts/afterinstall.sh script. — this removes the installer and resets some permissions changed by ./scripts/firstrun.sh. I would however not recommend doing this until you are sure that you do not need to reinstall.

Now, got to http://localhost/webproject/admin or use the link on the successful installation page.

Trouble Shooting

Speak to Lindsay.....

Steps

Throughout this webproject is a placeholder for whatever you decide to call the directory in which you are installing the framework!

1. Make sure that you do not have the default macOS version of the web server running. Use the ps ax command to see if there are any httpd processes running, or try to access 127.0.0.1 from your browser - if there is a response then you have a web server running. If you execute the terminal command:

   sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

   This is will stop the processes and also stop them from being started on a reboot. If for some reason you do not want to disable the daemon in the future then use the command:

   sudo apachectl stop

   Remember you will have to do this after every reboot if you want to use XAMPP.

   Note: you can use the built-in server but it does involve rather a lot of work and software upgrading, so I would not advise it unless you are very familiar with it.

2. Install a version of the LAMP stack.

   Make sure you are installing a version supporting the latest PHP.

   • XAMPP

     Do NOT install the default version that the site offers you as that is something called XAMPP-VM which, whilst it works fine, is rather more complicated to interact with. Find the version of XAMPP with the most recent PHP version.

   • MAMP is another possible program, however be warned that it installs adware so I cannot recommend it
3. Make sure that the Apache web server is running. You cannot run phpmyadmin wihtout it.
4. Find the root of your web server. It (usually) a directory called htdocs that will be somewhere in your server installation. If you are using XAMPP, then it is a directory inside the XAMPP folder - you may need to use the terminal command line to find it.

   I would strongly suggest making a link to it from your Desktop as this will simplify your life a lot.

5. If you don't already have a git GUI program, download and install the github desktop which you can find at https://desktop.github.com. Use this to clone the framework from git into the root directory of your web server. The framework reference is https://github.com/rivets/framework2.git.

   If you have problems cloning the repository you can download the zip file from github and unzip it. Then rename the directory to whatever you have chosen for your project.

   Note that you will not be able to use git pull to get updates to the framework if you do this so cloning is much the best way forward..

6. In Terminal, now cd into webproject and run ./scripts/firstrun.sh. This will set up necessary permissions and run composer. If composer is not available it will fetch a copy.

7. Now you need to create a MySQL database for your application using phpadmin which you can start from the control panel for your LAMP stack. Create an empty database with an appropriate name I suggest whatever you are using for webproject) and then create a user and grant access to the database for that user on localhost including a password. Do the equivalent of the sql commands:

   
   CREATE DATABASE webproject;
   GRANT ALL ON webproject.* TO username@localhost IDENTIFIED BY 'password';
                   

   Of course, you need to remember the username and password for subsequent steps… For convenience I often make the username the same as webproject.

8. Now go to the URL http://localhost/webproject/install.php in your browser and fill in the form that you see there (and remembering the database access username/password combination from above).

Post-install Clean up

When the installation has finished successfully, and you are absolutely sure that you are not going to have to reinstall, run the ./scripts/afterinstall.sh script. — this removes the installer and resets some permissions changed by ./scripts/firstrun.sh. I would however not recommend doing this until you are sure that you do not need to reinstall.

Now, got to http://localhost/webproject/admin or use the link on the successful installation page.

Trouble Shooting

Speak to Lindsay.....

Steps

Throughout this webproject is a placeholder for whatever you decide to call the directory in which you are installing the framework!

1. Install a version of the LAMP stack.

   Make sure you are installing a version supporting the latest PHP.

   • XAMPP
   • WAMP

   WAMP users may need to edit the http.conf file for Apache in order to enable the RewriteEngine which is needed by the framework. This is usually a matter of uncommenting a line in the file.

2. Make sure that the Apache web server is running. You cannot use phpmyadmin without it.
3. Find the root of your web server. It (usually) a directory called &8216;htdocs&8217; that will be somewhere in your server installation. If you are using XAMPP, then it is a directory inside the XAMPP folder - you may need to use the command line to find it. WAMP is similar, though the directory you are looking for is called "www".

   I would strongly suggest making a link to it from your Desktop as this will simplify your life a lot.

   Do not try to move your installation - this will just break things as full paths are written into config files. If you need to move the server installation then reinstall from scratch.

4. If you don't already have a git GUI program, download and install the github desktop which you can find at https://desktop.github.com or you could try the program at https://gitforwindows.org. Use this to clone the framework from git into the root directory of your web server. The framework reference is https://github.com/rivets/framework2.git.

   If you have problems cloning the repository you can download the zip file from github and unzip it. Then rename the directory that is created to whatever you have chosen for your project.

   Note that you will not be able to use git pull to get updates to the framework if you do this so cloning is much the best way forward..

5. You now need to run composer in the directory. Download and install the latest version of composer from https://getcomposer.org/download/. When you have done that successfully (making sure that if you are offered a choice of PHP versions that you pick the most recent), then you need to open a CLI window. You can use the standard Windows cmd line, or (preferably) the bash shell you can invoke from the git desktop or the version of bash that you can enable under Windows 10.

   Change directory to the root of your server and then into webproject. Now run the command composer install. This will install various packages that are needed by the framework. If you get errors it may be because the pHP version that is being used is wrong. Check your installation of the composer setup program.

6. Now you need to create a MySQL database for your application using phpmyadmin which you can start from the control panel for your LAMP stack. Create an empty database with an appropriate name — I suggest whatever you are using for webproject) — and then create a user and grant access to the database for that user on localhost including a password. Do the equivalent of the sql commands:

   
   CREATE DATABASE webproject;
   GRANT ALL ON webproject.* TO username@localhost IDENTIFIED BY 'password';
                   

   Of course, you need to remember the username and password for subsequent steps… For convenience I often make the username the same as webproject.

7. Next, in order to run the web based installer you may need to set some access permissions so that the web server can create files for you. It is very likely that you won't need to do this as XAMPP/WAMP tend to run be running using a user id that gives it permissions — you can find out if this is the case by skipping to the next step and seeing if you get an error from the installer. If you get no error then you are done, if you do get an error you are going to have to change some file permissions or ownerships.

   You need to give write permission to the web server user on

   • webproject
   • webproject/.htaccess
   • webproject/class/config
   • webproject/assets
   • Now go to the URL http://localhost/webproject/install.php in your browser and fill in the form that you see there (and remembering the database access username/password combination from above).

Post-install Clean up

When the installation has finished successfully, go into the “webproject” directory and remove the files “install.php” and the directory “install”, Remove any extra permissions that you granted on the “webproject” and “webproject/class” directories, and the .htaccess file. You can also delete the file “index.nodb.php” should you so wish.

Now, got to http://localhost/webproject/admin or use the link on the successful installation page.

Trouble Shooting

Speak to Lindsay.....