Project

General

Profile

Download (10 KB) Statistics
| Branch: | Tag: | Revision:
1
# CDM Data Portal
2

    
3
Drupal 7 modules and themes as web frontend to publish data hosted in a [cdm server](https://github.com/cybertaxonomy/cdm-server).
4

    
5
This project has a monolithic structure, that is it contains multiple projects in one git repository.
6

    
7
Project dependencies required for bundling the final installation package are managed via composer. 
8
Dependencies of sub-projects like *modules/cdm_dataportal*, *themes/zen_dataportal*, etc still have manually copied dependencies. 
9

    
10
## Project structure
11

    
12
* `./drush`: commands, configuration and site aliases for Drush
13
* `./debug`: scripts that help debugging problems with drupal multisite setups
14
* `./modules`: drupal modules, the actual **cdm_dataportal** module is found here. 
15
* `./scripts/composer`: scripts, installed by composer and manually added ones
16
* `./scripts/jenkins-ci`: scripts for testing, release, deployment in jenkins.
17
* `./site`: documentation source code, will be build by maven (see `pom.xml`)
18
* `./src`: java project with selenium tests
19
* `./themes`: drupal themes
20

    
21
**Generated folders which must not be comitted to the repository:**
22

    
23
* `./target`: target folder of maven, used for the side documentation (source in `./site`) and selenium tests (source in `./src`)
24
* `./screenshots`: screenshots taken during the selenium test execution
25
* `./vendor`: composer cache
26
* `./web`: final installation bundle of drupal 7 with modules, themes, profiles, etc. that is created by `composer update`
27

    
28
**Creation of the composer project**
29

    
30
The parent composer project (`./composer.json`) has been created using the official drupal project template:
31

    
32
~~~
33
composer create-project drupal-composer/drupal-project:7.x-dev -n dist
34
~~~
35

    
36
### On using composer with drupal projects
37

    
38
https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies
39

    
40
https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal
41

    
42
https://www.drupal.org/docs/develop/using-composer/managing-dependencies-for-a-custom-project
43

    
44

    
45

    
46
### Installation
47

    
48
**NOTE:** For detailed instructions which also cover the setup of apache and mysql please refer 
49
to: https://cybertaxonomy.eu/dataportal/installation
50

    
51
#### Download & extract
52

    
53
Download the latest release from https://cybertaxonomy.eu/download/dataportal/stable/ to the location where you want 
54
to install the cdm-dataportal Drupal 7 project e.g.
55

    
56
~~~
57
cd /var/www
58
wget https://cybertaxonomy.eu/download/dataportal/stable/drupal-7-cdm-dataportal-5.23.0.tar.gz
59
~~~
60

    
61
This archive contains a shallow clone of the whole project together with a ready to use drupal 7 installation with the 
62
cdm-dataportal module, zen_dataportal theme and other requirements. The drupal-7 installation is in the sub folder `./web`
63

    
64
extract and adapt the ownership of the some folders:
65

    
66
~~~
67
tar -xzf drupal-7-cdm-dataportal-5.23.0.tar.gz
68
./drupal-7-cdm-dataportal/scripts/admin/fix-permissions.sh  --web-user www-data
69
~~~
70

    
71
##### Apache2 configuration
72

    
73
You may now want to copy the apache 2 site configuration files from `scripts/apache2.4/` to `/etc/apache2/sites-available/` 
74
and to activate one of them, preferably the ssl site configuration:
75

    
76
~~~
77
cd /var/www
78
sudo cp drupal-7-cdm-dataportal/scripts/apache2.4/dataportal.test* /etc/apache2/sites-available/
79
sudo a2ensite dataportal.test-ssl.conf
80
sudo systemctl restart apache2
81
~~~
82

    
83
##### Site installation
84

    
85
Now you are prepared to install a dataportal drupal site. 
86

    
87
A template for the below script can be found in `scripts/user/`
88
Make an executable copy from `new-site.sh.template` as `new-site.sh` 
89

    
90
~~~
91
cp new-site.sh.template new-site.sh; chmod u+x new-site.sh
92
~~~
93

    
94
Adapt the below shown variables in the script to match your desired setup:
95

    
96
~~~
97
################################################################
98
## Configure below variables
99

    
100
SITE_NAME='test-site'
101

    
102
# HOST_NAME and PROTOCOL determine the base URL of the new site
103
# The default values will form the base URL like http://dataportal.test
104
# See also MULTI_SITE below
105
HOST_NAME='dataportal.test'
106
PROTOCOL='https' # values 'http' ot https'
107
# For MULTI_SITE=0 the site will be installed at the base BASE_URL
108
# In multisite setups (MULTI_SITE=1), however, the site URL results 
109
# in http://dataportal.test/test-site
110
# !! Mutisite support ist still experimental !!
111
MULTI_SITE=0 # values: 1 = true, 0 or other = false
112

    
113
ADMIN_USR='admin'
114
ADMIN_PWD='change--me'
115
ADMIN_EMAIL='admin@dataportal.test'
116

    
117
MYSQL_USR='root'
118
MYSQL_PWD='change--me'
119
DB_PREFIX='drupal7_dataportal_'
120

    
121

    
122
################################################################
123
~~~
124

    
125
Execute the script **from within the folder** `scripts/user/`, otherwise the `$DRUPAL_ROOT` variable will not match the `./web` folder !
126

    
127
Once the script has fished it will print out the final URL of the new site together with other useful information.
128

    
129
### Update - method 1
130

    
131
**Strategy**: Downloading of the installation package for a new release of the cdm-dataportal and replacing the old 
132
installation by the content of the installation package.
133

    
134
* Pro: Few simple steps.
135
* Con: The steps described here are not suitable for multi-site installation or when additional modules are installed.
136

    
137
~~~
138
cd /var/www
139
mv drupal-7-cdm-dataportal drupal-7-cdm-dataportal.last
140
~~~
141

    
142
remove old installation packages
143

    
144
~~~
145
rm drupal-7-cdm-dataportal*.tar.gz*
146
~~~
147

    
148
now follow the steps in the chapter **Download & extract** above.
149

    
150
finally copy the default site to the new installation 
151

    
152
~~~
153
cp -r drupal-7-cdm-dataportal.last/web/sites/default/ drupal-7-cdm-dataportal/web/sites/
154
~~~
155

    
156
apply any pending database updates
157

    
158
~~~
159
drush updatedb
160
drush cc all
161
~~~
162

    
163
Once you have confirmed that the updated installation is working correctly:
164

    
165
~~~
166
rm -r drupal-7-cdm-dataportal.last
167
~~~
168

    
169
### Update - method 2
170

    
171
**Strategy**: In-place updating of the installation by making use of git and drush or composer. 
172

    
173
*THIS METHOD IS RECOMMENDED FOR MOST SITUATIONS**
174

    
175
* Pro: Update of drupal and custom modules independent of what is provided by the installation package.
176
* Con: Initial preparation is more complex, 
177

    
178
#### Preparation
179

    
180
**Install composer v 1.10.x**
181

    
182
!!! *Composer v2.x would fail to preserve existing site installations* !!!
183

    
184
In case the version provided by apt is too old (<1.10), you can install composer manually in the project 
185
directory `/var/www/drupal-7-cdm-dataportal`. In the following we assume you have installed composer this way and 
186
will use `./composer` instead of `composer`.
187

    
188
~~~
189
cd /var/www/drupal-7-cdm-dataportal
190
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
191
php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
192
php composer-setup.php --filename=composer --version 1.10.22
193
php -r "unlink('composer-setup.php');"
194
~~~
195

    
196
The above commands fails with "Installer corrupt"? Please update the corresponding command with the new one from [http//getcomposer.org/download/](http//getcomposer.org/download/). It is **important not use use a version > 1.*!**
197

    
198
**Un-shallow the installation package**
199

    
200
The installation package contains a shallow clone of the git repository only. In order to easily upgrade the 
201
dataportal-module it is highly recommended to un-shallow the git repository clone
202

    
203
~~~
204
git fetch --unshallow
205
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
206
git fetch origin
207
git checkout origin/master
208
~~~
209

    
210
**install dependencies**
211

    
212
This will also install **drush**
213

    
214
~~~
215
 ./composer install --no-dev
216
~~~
217

    
218
#### Updating to a specific cdm-dataportal release
219

    
220
NOTE: The modules and themes in the `./web/sites/all/` are sym-linked to the source code in `./modules` and `./themes`. 
221
Hence, updating the dataportal only involves checking out the according release from the git remote:
222

    
223
To see the list of available release tags:
224

    
225
~~~
226
git tag --list | egrep '[0-9]+\.[0-9]+\.[0-9]+' | sort -V
227
~~~
228

    
229
Checkout the release tag. For example to checkout the release `5.23.0`:
230

    
231
~~~
232
git checkout 5.23.0
233
scripts/admin/fix-permissions --web-user www-data
234
~~~
235

    
236
Git will respond with a warning that "*You are in 'detached HEAD' state.*", this is OK and no need to be concerned.
237

    
238
Finally apply any pending database updates and clear the cache. **NOTE**: Below we assume that the command is being 
239
executed in the installation package root e.g. `/var/www/drupal-7-cdm-dataportal` and that the site is available under 
240
https://dataportal.test. Please adapt to your specific settings if needed.
241

    
242
~~~
243
./vendor/drush/drush/drush -r /var/www/drupal-7-cdm-dataportal/web/ -l https://dataportal.test updatedb
244
./vendor/drush/drush/drush -r /var/www/drupal-7-cdm-dataportal/web/ -l https://dataportal.test cc all
245
~~~
246

    
247
#### Updating drupal and modules
248

    
249
The drupal-7-cdm-dataportal installer provides a script for convenient and secure updating of single or multisite setups.
250
It will 
251

    
252
1. create backups
253
1. set the site(s) to maintenance mode   
254
1. Update drupal core and contributed modules via `composer`
255
1. Run any pending database updates and clear the caches
256

    
257
A brief help for this script is available from `scripts/admin/update-dependencies.sh --help` 
258

    
259
~~~
260
USAGE: update-dependencies.sh [--deactivate-install] [--multi-site] [--mailto <ADDRESS>]
261
  --deactivate-install :  The install.php will be hidden by appending '.off' to the filename
262
  -h, --help:  Print this help text
263
  --mailto <ADDRESS>:  send a email to the ADDRESS with a log of the update process
264
  --multi-site:  Do a multi-site update. Requires dataportals-drush. 
265
        See https://dev.e-taxonomy.eu/svn/trunk/server-scripts/dataportal-admin/
266
  --site-url:  The site url to be used with drush. This option disables the --multi-site option
267
~~~
268

    
269

    
270

    
271
Update a single site installation with default site URL
272

    
273
~~~
274
scripts/admin/update-dependencies.sh --deactivate-install 
275
~~~
276

    
277
Update a single site installation with custom site URL
278

    
279
~~~
280
scripts/admin/update-dependencies.sh --deactivate-install --site-url http://edit.test/d7/cichorieae/ 
281
~~~
282

    
283
Update a multi-site installation with custom site URL
284

    
285
~~~
286
scripts/admin/update-dependencies.sh --deactivate-install --multi-site
287
~~~
(3-3/5)