Getting Started

This page lists installation instructions for both local and server installation.

1. Local Install

Want to give Constituent Correspondence Data Tool a quick run? or want to develop and test new features? Try installing locally using docker.

1.1 Install requirements

Following are the required tools to get started with the local installation:

1. docker
2. git

1.2 Clone the repo

Clone the repo using the following command:

# This command will clone the Constituent Correspondence Data Tool
git clone https://github.com/wvulibraries/ccdt.git

1.3 Start docker environment

The docker-compose.yml describes each container that is needed for the application. Compose will download or build each individual container that is used in the project. Run the following to start:

# Change directory to project root
cd ccdt

To try CCDT using the development version Run the following to start:

docker-compose -f docker-compose.dev.yml up

Optionally use the production setup which includes the nginx webserver. Note: This will require you to setup your ssl certificates. See production notes.

Run the following to start:

docker-compose up

1.4 Setup the project

Once the provisioning is finished, the environment will have all the necessary containers running. If running in development mode the following command it should show you 3 containers (ccdt_php, ccdt_database_1, tika_service).

docker ps

1.5 Edit the UserTableSeeder.php

The UserTableSeeder.php contains 2 default users admin@admin.com (the admin users) and test@test.com both with the password testing. Prior to running the install scripts you may want to modify the following file and add your accounts for use.

/src/project-css/database/seeds/UsersTableSeeder.php

1.6 Running configuration scripts

The following is only required if you are not using an existing database.

Next change to the scripts directory

cd /ccdt/scripts/

To insert the users into the database run the following script.

./seed.sh 

Optionally if you wish to update the application during your setup you can run the update-provision-app.sh which will update the composer dependencies, generate a new laravel key and seed the database users. (Note: If you choose this option do not run the seed.sh script)

./update-provision-app.sh 

1.7 Accessing the Application

To access the Application on your local system you will use localhost:9000 in your web browser.

2. Server Install

2.x Request Entity Too Large

This was seen when we tested the application under Apache. If you get the error message "Request Entity Too Large" your flat file is larger than the default size of 8 Meg. To increase this open the /etc/php.ini and change the post_max_size = 8M set it to an amount larger than the file you are trying to import.

3. Creating Collections and Importing Flat files

3.x Flat File Storage

Once uploaded the flat files are stored in the storage fold currently the path on this repo is /src/project-css/storage/app/flatfiles/

3.x Database File Storage

Files associated to a table that need to be manually uploaded should be placed /src/project-css/storage/app/{tablename}. This directory is automatically created during the import process. If there are sub-folders they can be included in the folder as well along with the files.

4.x Development Notes

4.x Accessing the Application

to access the application in development use http://localhost:9000

4.x Running PHPUnit

run a interactive terminal in the ccdt_php docker container and then run phpunit. Example below

docker exec -it ccdt_php /bin/bash
vendor/bin/phpunit

If you want to have a html report of the coverage test run the following instead.

vendor/bin/phpunit --coverage-html=coverage

5.x Production Notes

5.x Storage Folder Permissions

If wish to link the data storage folder to a location outside of the docker container (to a path on the parent VM):

To make this work with the Laravel docker container (which is Ubuntu based) you have to set the folder permissions so they are owned by www-data and group www-data with directory mode 775 and file mode 664. The UID is 33 and the GID is 33 in the Laravel docker container. Depending on the host OS and web server versions you are using in the parent VM you will need to change its UID/GID to match (in /etc/passwd and /etc/group) and restart the Webserver or else it will not function correctly.

The error message we saw that clued us in to this was (this is an approximation of what we saw):

ErrorException: file_put_contents(/var/www/html/laravel-project/storage/framework/views/B6BETDiE1wtExOa5pXJJjPLFcLWXAzEyP6iTG8B6): failed to open stream: Permission denied in /var/www/html/laravel-project/vendor/laravel-project/framework/src/Illuminate/Filesystem/Filesystem.php:111

If you get this error many forums on line suggest solving this by doing:

chmod -R 777 /path/to/storage/

This is not a good idea from a security standpoint. If owned by the web server, the permissions for this folder can be:

chmod -R 755 /path/to/storage/

or we used:

chmod -R 775 /path/to/storage/   (with GID also set to web-server)

After you change the UID/GID of Apache or Nginx in /etc/passwd and /etc/group to match the default web-server UID/GID of your Laravel docker container then don't forget to do:

chmod -R nginx:nginx /path/to/storage   (or substitute apache/httpd/www-data as appropriate)

If your parent/host VM is Ubuntu and you are using Apache with UID/GID 33/33 you won't need to change the UID/GID.

Alternately (we did not test this) you may be able to set the UID/GID of the storage folder in docker to match the web-server of your parent VM (i.e. chown -R 996:994 /path/to/storage/ for nginx). This may actually make more sense if you have a lot of different containers with different web-servers running on the parent VM.