Project

General

Profile

Download (9.09 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 `./web` sub folder:
65

    
66
~~~
67
tar -xzf drupal-7-cdm-dataportal-5.23.0.tar.gz
68
sudo chown -R :www-data drupal-7-cdm-dataportal/web
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
~~~
233

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

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

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

    
245
#### Updating drupal and modules
246

    
247
First create a backup of the installation:
248

    
249
~~~
250
cd /var/www/drupal-7-cdm-dataportal 
251
tar -czf ../drupal-7-cdm-dataportal-backup-$(date -I).tar.gz ./
252
~~~
253

    
254
Now use `composer` to update drupal core and contributed modules:
255

    
256
~~~
257
./composer update --no-dev
258
~~~
259

    
260
Run any pending database updates and clear the caches
261

    
262
~~~
263
./vendor/drush/drush/drush -r /var/www/drupal-7-cdm-dataportal/web/ -l https://dataportal.test updatedb
264
./vendor/drush/drush/drush -r /var/www/drupal-7-cdm-dataportal/web/ -l https://dataportal.test cc all
265
~~~
(3-3/5)