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
sudo cp drupal-7-cdm-dataportal/scripts/apache2/dataportal.test* /etc/apache2/sites-available/
78
sudo a2ensite dataportal.test-ssl.conf
79
sudo systemctl restart apache2
80
~~~
81

    
82
##### Site installation
83

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

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

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

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

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

    
99
SITE_NAME='test-site'
100

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

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

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

    
120

    
121
################################################################
122
~~~
123

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

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

    
128
### Update - method 1
129

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

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

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

    
141
remove old installation packages
142

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

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

    
149
finally copy the default site to the new installation 
150

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

    
155
apply any pending database updates
156

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

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

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

    
168
### Update - method 2
169

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

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

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

    
177
#### Preparation
178

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

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

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

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

    
195
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.*!**
196

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

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

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

    
209
**install dependencies**
210

    
211
This will also install **drush**
212

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

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

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

    
222
To see the list of available release tags:
223

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

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

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

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

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

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

    
246
#### Updating drupal and modules
247

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

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

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

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

    
268

    
269

    
270
Update a single site installation with default site URL
271

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

    
276
Update a single site installation with custom site URL
277

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

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

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