-
Notifications
You must be signed in to change notification settings - Fork 8
Expand file tree
/
Copy pathINSTALL.html
More file actions
1815 lines (1708 loc) · 64.1 KB
/
INSTALL.html
File metadata and controls
1815 lines (1708 loc) · 64.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="generator" content="http://www.nongnu.org/elyxer/"/>
<meta name="create-date" content="2013-09-16"/>
<link rel="stylesheet" href="http://elyxer.nongnu.org/lyx.css" type="text/css" media="all"/>
<title>ERcore Installation Guide</title>
</head>
<body>
<div id="globalWrapper">
<h1 class="title">
ERcore Installation Guide
</h1>
<h2 class="Date">
[September 16, 2013]
</h2>
<div class="Unindented">
This document describes how to install ERcore V1.1 on a target system. The first section provides system requirements and a high level overview of the installation process. Subsequent sections provide more detail and include troubleshooting suggestions and common site customizations. The intended audience for this document are system administrators and ERcore developers.
</div>
<div class="fulltoc">
<div class="tocheader">
Table of Contents
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Section-1">Section 1: System requirements and installation overview</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-1.1">Subsection 1.1: Server Requirements</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-1.2">Subsection 1.2: A word about PostgreSQL</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-1.3">Subsection 1.3: PHP.INI parameters</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-1.4">Subsection 1.4: Drupal module and callable library requirements</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-1.5">Subsection 1.5: Installation summary</a>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-2">Section 2: Installation kits & their location</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-2.1">Subsection 2.1: Recommended releases</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-2.2">Subsection 2.2: Non-standard versions</a>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-3">Section 3: Target location</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-4">Section 4: Step 1: Backup target site</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-5">Section 5: Step 2: Check PHP.INI parameters</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-6">Section 6: Step 3: Installing prerequisites</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-6.1">Subsection 6.1: PHPExcel Library download</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-6.2">Subsection 6.2: PHPExcel Library installation</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-6.3">Subsection 6.3: Drupal module download</a>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-7">Section 7: Step 4: Installing ERcore files</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-7.1">Subsection 7.1: Downloading and decompressing ERcore kit</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-7.2">Subsection 7.2: Removing ERcore from previous install</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-7.3">Subsection 7.3: Installing ERcore files on target</a>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-8">Section 8: Step 5: Enable ERcore in Drupal</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-9">Section 9: Step 6: Check installation status and troubleshoot</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-9.1">Subsection 9.1: Basic installation status</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-9.2">Subsection 9.2: ERcore installation reset</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-9.3">Subsection 9.3: Apache error log</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-9.4">Subsection 9.4: Clearing caches</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-9.5">Subsection 9.5: Double asterisk problem</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-9.6">Subsection 9.6: MySQL server error</a>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-10">Section 10: Step 7: Initial ERcore configuration</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-11">Section 11: Step 8: Drupal permissions configuration </a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-11.1">Subsection 11.1: ERcore roles and permissions reset</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-11.2">Subsection 11.2: Drupal permissions page</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-11.3">Subsection 11.3: Reorder roles</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-11.4">Subsection 11.4: ERcore permissions adjustment</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsubsection--1">Subsubsection: Administration menu</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--2">Subsubsection: EPSCoR Reporting</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--3">Subsubsection: Field Permissions</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--4">Subsubsection: Filter</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--5">Subsubsection: Node</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--6">Subsubsection: System</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsubsection--7">Subsubsection: User</a>
</div>
</div>
</div>
<div class="toc">
<a class="Link" href="#toc-Section-12">Section 12: ERcore Update Process</a>
</div>
<div class="tocindent">
<div class="toc">
<a class="Link" href="#toc-Subsection-12.1">Subsection 12.1: Create a test site</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-12.2">Subsection 12.2: ERcore Update</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-12.3">Subsection 12.3: Data migration</a>
</div>
<div class="toc">
<a class="Link" href="#toc-Subsection-12.4">Subsection 12.4: Production site update</a>
</div>
</div>
</div>
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-1">1</a> System requirements and installation overview
</h1>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.1">1.1</a> Server Requirements
</h2>
<div class="Unindented">
ERcore is known to work with the following specific versions of Drupal 7 server components:
</div>
<ul>
<li>
Drupal: 7.14 through 7.22
</li>
<li>
MySQL: 5.1.66-0+squeeze1, 5.1.58-1ubuntu1, 5.5.31-1.fc17.x86_64 (Fedora)
</li>
<li>
PHP: 5.3.3-7+squeeze15, 5.3.6-13ubuntu3.8, 5.4.16-1.fc17.x86_64 (Fedora)
</li>
<li>
Apache: 2.2.16 (Debian), 2.2.20 (Ubuntu), 2.2.23-1.fc17.x86_64 (Fedora)
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.2">1.2</a> A word about PostgreSQL
</h2>
<div class="Unindented">
Drupal is described as supporting both MySQL and PostgreSQL as the underlying database storage engine. However, there appears to be a lag in supporting fixes to PostgreSQL problems in Drupal Core. This is just a word of warning for those who plan to use PostgreSQL instead of MySQL. More information about this issue can be found at:
</div>
<ul>
<li>
<a class="URL" href="http://drupal.org/node/1524250">http://drupal.org/node/1524250</a>
</li>
<li>
<a class="URL" href="http://groups.drupal.org/node/207358">http://groups.drupal.org/node/207358</a>
</li>
<li>
<a class="URL" href="https://drupal.org/node/1866640">https://drupal.org/node/1866640</a>
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.3">1.3</a> PHP.INI parameters
</h2>
<div class="Unindented">
Several PHP system parameters defined in <tt>php.ini</tt> can cause problems on the Apache target server when set too small. The following are suggested minimum values for two of these:
</div>
<ul>
<li>
<tt>max_execution_time</tt> — set to 240
</li>
<li>
<tt>memory_limit</tt> — set to 256M.
</li>
</ul>
<div class="Unindented">
These should be set in <tt>/apache2/php.ini</tt> prior to ERcore installation. If the <tt>drush</tt> utility is used, they should be set in <tt>/cli/php.ini</tt> as well.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.4">1.4</a> Drupal module and callable library requirements
</h2>
<div class="Unindented">
<a class="Label" name="sub: DrupalModules"> </a>The following callable libraries are used by ERcore:
</div>
<ul>
<li>
PHPExcel, v1.7.9
</li>
</ul>
<div class="Unindented">
The latest version of the following Drupal modules are used by ERcore:
</div>
<ul>
<li>
bundle_copy
</li>
<li>
computed_field
</li>
<li>
ctools
</li>
<li>
date
</li>
<li>
date_api
</li>
<li>
date_popup
</li>
<li>
date_repeat_field
</li>
<li>
date_views
</li>
<li>
entity
</li>
<li>
entity_token
</li>
<li>
entityreference
</li>
<li>
entityreference_cascade_delete (ercd)
</li>
<li>
entityreference_prepopulate
</li>
<li>
field_group
</li>
<li>
field_permissions
</li>
<li>
flag
</li>
<li>
libraries
</li>
<li>
link
</li>
<li>
markup
</li>
<li>
nodeaccess_userreference
</li>
<li>
page_manager
</li>
<li>
php
</li>
<li>
rules
</li>
<li>
rules_admin
</li>
<li>
rules_scheduler
</li>
<li>
select_or_other
</li>
<li>
views
</li>
<li>
views_content
</li>
<li>
views_data_export
</li>
<li>
views_php
</li>
<li>
views_ui
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.5">1.5</a> Installation summary
</h2>
<div class="Unindented">
ERcore is a Drupal <a class="URL" href="http://drupal.org/node/1011196">sandbox project</a> and therefore requires a more complicated installation procedure than a Drupal full project. The following steps must be performed to install ERcore.
</div>
<ol>
<li>
<u>Install PHPExcel library.</u><br/>
<br/>
On the target site, create a directory in <tt>DOCUMENT_ROOT/sites/all/libraries/</tt> named <tt>/PHPExcel/</tt>. Download and decompress version 1.7.9 of the <a class="URL" href="http://phpexcel.codeplex.com/">PHPExcel library</a>. Copy the decompressed directory tree into the <tt>/PHPExcel/</tt> directory on the target.<br/>
</li>
<li>
<u>Download prerequisite modules.</u><br/>
<br/>
Download latest version of Drupal modules listed in Section <a class="Reference" href="#sub: DrupalModules">1.4↑</a> using either the Drupal module interface or the drush utility download command.
</li>
<li>
<u>Install ERcore files.</u><br/>
<br/>
On the <a class="URL" href="http://drupalcode.org/sandbox/shixish/1837936.git/tags">tags page</a> of the ERcore git repository, click the hotlink for the desired ERcore version. On the resulting page, click <i>snapshot</i> to download the ERcore files in <tt>tar.gz</tt> format. On the target site, create a directory named <tt>/er/</tt> in <tt>DOCUMENT_ROOT/sites/all/modules/</tt>. If the directory already exists, delete its contents. Decompress the ERcore snapshot and copy its contents to the <tt>/er/</tt> target directory.
</li>
<li>
<u>Install ERcore module.</u><br/>
<br/>
In Drupal, enable the <i>EPSCoR Reporting</i> module in the EPSCOR section of the <i>Modules</i> page. A progress bar is displayed during the installation process, followed by an installation status page. Note that installation may take several minutes.
</li>
</ol>
<div class="Unindented">
The remainder of this document describes installation in more detail and includes troubleshooting suggestions and common site customizations. Section <a class="Reference" href="#sec:ercore-update-process">12↓</a> describes updating ERcore software to a new version.
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-2">2</a> Installation kits & their location
</h1>
<div class="Unindented">
<a class="Label" name="sec:InstallationKits"> </a>An ERcore kit, as defined in this document, is simply a compressed <tt>/er/</tt> directory tree in <tt>tar.gz</tt> file format and which was downloaded from the ERcore <i>git repository</i>. The git software uses the term <i>snapshot</i> to refer to a compressed directory tree, so an ERcore kit and a snapshot from the ERcore git repository are essentially the same thing.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-2.1">2.1</a> Recommended releases
</h2>
<div class="Unindented">
ERcore recommended releases can be found and downloaded with the following steps:
</div>
<ol>
<li>
Navigate to the ERcore git repository url at<ul>
<li>
<a class="URL" href="http://drupal.org/sandbox/shixish/1837936">http://drupal.org/sandbox/shixish/1837936</a>
</li>
</ul>
</li>
<li>
Click <i>Repository viewer</i> under the <i>Development </i>header arriving at the <i>Git Summary</i> page. (It is not necessary to login to view the repository.)
</li>
<li>
The section named <i>tags</i> at the bottom of the page lists the recommended releases for ERcore. The current recommended release for ERcore is version <tt>7.x-2.x</tt>.
</li>
<li>
Click the hotlink for the desired version of ERcore, taking you to the <i>commit</i> page for that tag.
</li>
<li>
Click <i>snapshot</i> to download the compressed directory tree (installation kit) for that version of ERcore in <tt>tar.gz</tt> format.
</li>
</ol>
<div class="Unindented">
It should be noted that the filename of this compressed file is <i>computer generated</i> and has no memorable relationship to the ERcore version number. An example snapshot filename is <tt>1837936-bae76ad.tar.gz</tt>. You are encouraged to rename this file to something more memorable like <tt>erkit-v7.x-2.x.tar.gz</tt>. Note also that the top-level directory name within this compressed file also computer generated (e.g., <tt>1837936-bae76ad</tt>) and not <tt>/er/</tt> as one might expect.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-2.2">2.2</a> Non-standard versions
</h2>
<div class="Unindented">
In some cases it is necessary to install a non-standard version of ERcore on a target system, one that does not have a <i>tag</i> associated with it. Since the git repository for ERcore maintains snapshots for every committed change to the source code, any of these snapshots can be installed on a target system. The desired snapshots can be found with the following steps:
</div>
<ol>
<li>
Perform steps 1--2 above, arriving at the <i>Git Summary</i> page.
</li>
<li>
The section named <i>heads</i> at the bottom of the page lists pointers to git source code <i>branches</i>. Currently there are 2 source code branches for ERcore: <tt>7.x-1.x</tt> and <tt>7.x-1.</tt>x-dev.
</li>
<li>
Click the hotlink for the desired branch head of ERcore, taking you to the <i>shortlog</i> page listing all commits for that branch
</li>
<li>
Identify which commit you wish to install on the target system and click <i>snapshot</i> to the right of that entry. This will download a compressed directory tree for that version of ERcore in tar.gz format.
</li>
<li>
Alternatively, clicking <i>commit</i> to the right of the entry will take you to a informational page about the commit which also includes a timestamp. This page also allows you to download a compressed directory tree by clicking <i>snapshot</i>.
</li>
</ol>
<div class="Unindented">
As with any snapshot from git, the downloaded filename is generated. You are encouraged to rename this file to something more memorable like <tt>er-v7.x-1.x-2013-03-15-2051.tar.gz</tt>.
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-3">3</a> Target location
</h1>
<div class="Unindented">
<a class="Label" name="sec:TargetLocation"> </a>In the description below, the mnemonics <tt><target-modules></tt> and <tt><target-libraries></tt> are used to represent the full path of the <tt>/modules/</tt> and <tt>/libraries/</tt> directories where ERcore and required libraries should be installed. These paths can be determined as follows:
</div>
<pre class="LyX-Code">
<target-modules> ::= DOCUMENT_ROOT/sites/all/modules/
<target-libraries> ::= DOCUMENT_ROOT/sites/all/libraries/
</pre>
<div class="Unindented">
Where <tt>DOCUMENT_ROOT</tt> is defined by the target site Drupal web server. The correct value for <tt>DOCUMENT_ROOT</tt> can be determined from Drupal as follows:
</div>
<ul>
<li>
navigate to the PHP Status page via <i>Reports</i> ▷ <i>Status report</i> ▷ <i>PHP (more information)</i> (or http://<your-site>/admin/reports/status/php)
</li>
<li>
search for <tt>DOCUMENT_ROOT</tt> in the <i>Apache Environment</i> section on this page to determine the symbol’s value. A typical value for Turnkey appliances is <tt>/var/www/drupal7/</tt>.
</li>
</ul>
<h1 class="Section">
<a class="toc" name="toc-Section-4">4</a> Step 1: Backup target site
</h1>
<div class="Unindented">
<a class="Label" name="sec:Backup-target-site"> </a>Prior to installing ERcore, it is strongly advised that you make a backup of key files on your target system. These include MySQL database, the <tt>/modules/</tt> directory tree, the <tt>php.ini</tt> files, and any other important files. If something goes wrong with the installation of ERcore, you can restore your server with this backup. Use your favorite utility to perform this backup.
</div>
<div class="Indented">
Ideally, the backup should be performed when no one is using Drupal. One way to accomplish this is with the following Apache commands to stop and restart the server:
</div>
<pre class="LyX-Code">
apachectl -k stop
...do backup here...
apachectl -k restart
</pre>
<h1 class="Section">
<a class="toc" name="toc-Section-5">5</a> Step 2: Check PHP.INI parameters
</h1>
<div class="Unindented">
<a class="Label" name="sec:Check-PHP-parameters"> </a>Several PHP system parameters defined in <tt>php.ini</tt> can cause problems on the Apache target server when set too small. The following are suggested minimum values for two of these:
</div>
<ul>
<li>
<tt>max_execution_time</tt> — set to 240
</li>
<li>
<tt>memory_limit</tt> — set to 256M.
</li>
</ul>
<div class="Unindented">
The current values of these parameters can be determined from Drupal as follows:
</div>
<ul>
<li>
navigate to the PHP Status page via <i>Reports </i> ▷ <i> Status report </i> ▷ <i> PHP (more information)</i> (or /admin/reports/status/php)
</li>
<li>
search for the above symbols on this page to determine their current values on the server
</li>
<li>
search for <tt>php.ini</tt> on this page to determine the location of the <tt>php.ini</tt> file if the parameters need modification. A typical location for this file is <tt>/etc/php5/apache2/php.ini</tt>
</li>
</ul>
<div class="Unindented">
These two parameters should also be adjusted for command-line utilities on the target system (for the drush utility used in this installation procedure). This is accomplished by editing the <tt>php.ini</tt> file in <tt>/cli/</tt> directory parallel to the <tt>/apache2/</tt> directory.
</div>
<div class="Indented">
Another PHP parameter that has proven useful on occasion is <tt>display_errors</tt>. If users of your site encounter a blank page without any error message (lovingly known as a White Page Of Death - WPOD), setting <tt>display_errors = On</tt> can sometimes help determine what the problem is.
</div>
<div class="Indented">
If any changes are made to <tt>php.ini</tt>, the Apache server must be restarted to activate the changes. The following shell command does this:
</div>
<pre class="LyX-Code">
apachectl -k restart
</pre>
<h1 class="Section">
<a class="toc" name="toc-Section-6">6</a> Step 3: Installing prerequisites
</h1>
<div class="Unindented">
<a class="Label" name="sec:Installing-prerequisites"> </a>The ERcore package relies on approximately 20 underlying Drupal modules, each of which must be downloaded prior to installing ERcore. While this can be accomplished using the Drupal web-based interface, it is considerably faster to use the <i>drush command-line utility</i> to perform these downloads. In addition to the Drupal modules, an API library for Excel spreadsheets must also be downloaded to the target system. This section describes how to install these prerequisites on the target system.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-6.1">6.1</a> PHPExcel Library download
</h2>
<div class="Unindented">
This step can be done in numerous ways, depending on your Unix experience, preferences, and needs. This subsection however assumes you are using FileZilla (or a similar graphical file management tool) on a Windows machine. You will need a local temporary directory to decompress the PHPExcel kit into and you will need FileZilla windows to access this local temporary directory and the target system.
</div>
<div class="Indented">
Perform the following steps to download the library kit to your local system and decompress it:
</div>
<ol>
<li>
Access <a class="URL" href="http://phpexcel.codeplex.com/">http://phpexcel.codeplex.com/</a> in a web browser.
</li>
<li>
In the <i>Downloads</i> section, click the hot link after <i>Current release</i>: (currently PHPExcel 1.7.9)
</li>
<li>
Click hot link under <i>Recommended download</i>. Alternatively, the <i>Code only (no Documentation)</i> download may be used if PHPExcel documentation is not required on your site.
</li>
<li>
Click <i>save file</i> to the local Windows machine, noting location
</li>
<li>
Using Windows Explorer, select the local copy of this kit. Right-Click the file and select <i>Extract All...</i> to decompress the zip file to a local directory.
</li>
</ol>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-6.2">6.2</a> PHPExcel Library installation
</h2>
<div class="Unindented">
In the description below, the mnemonic <tt><target-libraries></tt> is used to represent the full path of the <tt>/libraries/</tt> directory where PHPExcel should be installed. This path can be determined as follows:
</div>
<pre class="LyX-Code">
<target-libraries> ::= DOCUMENT_ROOT/sites/all/libraries/
</pre>
<div class="Unindented">
Section <a class="Reference" href="#sec:TargetLocation">3↑</a> describes the definition of <tt>DOCUMENT_ROOT</tt> on the target system. Note that the <tt>/libraries/</tt> directory is “parallel to” the <tt>/modules/</tt> directory. Perform the following steps to install the PHPExcel library files to the target system from the kit downloaded in the previous subsection:
</div>
<ol>
<li>
Use FileZilla to login to the target site.
</li>
<li>
In the FileZilla “remote site” pane, navigate to the <tt><target-libraries></tt> directory on the target system.
</li>
<li>
Create the directory <tt><target-libraries>/PHPExcel/</tt> if it does not yet exist. This is the location where the PHPExcel library files will exist on the target system.
</li>
<li>
In the FileZilla “local site” pane, navigate to the decompressed PHPExcel kit that was created above. The following two files should be in this directory: <tt>Classes</tt> (a directory) and <tt>changelog.txt</tt>.
</li>
<li>
Copy the contents of this directory from local site into the <tt>/PHPExcel/</tt> directory on the target system.
</li>
</ol>
<div class="Unindented">
When finished, check that the following files exist at the target site:
</div>
<pre class="LyX-Code">
DOCUMENT_ROOT/sites/all/libraries/PHPExcel/changelog.txt
DOCUMENT_ROOT/sites/all/libraries/PHPExcel/Classes/PHPExcel.php
</pre>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-6.3">6.3</a> Drupal module download
</h2>
<div class="Unindented">
<a class="Label" name="sub:DrupalModuleDownload"> </a>The <i>drush command-line utility</i> is used to update Drupal and to download required prerequisite projects and modules prior to installing ERcore. The following commands assume a standard Turnkey Drupal 7 appliance installation. If the target system directory tree is not structured as described above, change the cd command-line to meet your needs. See Section <a class="Reference" href="#sec:TargetLocation">3↑</a> to determine the directory tree structure of your target system. See Section <a class="Reference" href="#sub: DrupalModules">1.4↑</a> for the list of required Drupal modules.
</div>
<div class="Indented">
Perform these commands on the target system.
</div>
<pre class="LyX-Code">
cd DOCUMENT_ROOT
drush up
cd DOCUMENT_ROOT/sites/all/modules
drush dl bundle_copy computed_field ctools date date_api date_popup
drush dl date_repeat_field date_views entity entity_token
drush dl entityreference entityreference_prepopulate field_group
drush dl field_permissions flag libraries link markup
drush dl nodeaccess_userreference page_manager php rules
drush dl rules_admin rules_scheduler select_or_other views
drush dl views_content views_data_export views_php views_ui
drush en entityreference
</pre>
<div class="Unindented">
If any of the above modules are already installed on your system, a warning message will be displayed. “No release history” warnings can also be ignored.
</div>
<div class="Indented">
The last <tt>drush</tt> command listed above is required to prevent an error later in the installation process. It enables the <tt>entityreference</tt> module within Drupal prior to installing ERcore with the steps below.
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-7">7</a> Step 4: Installing ERcore files
</h1>
<div class="Unindented">
<a class="Label" name="sec:Installing-ERcore-files"> </a>This step can be done in numerous ways, depending on your Unix experience, preferences, and needs. However, this section assumes you are running FileZilla (or a similar graphical file management tool) on a Windows machine. You will need a local temporary directory to decompress the ERcore kit into and you will need FileZilla windows to access the target system <tt><target-modules></tt> directory. This section also assumes you have the 7-ZIP utility (or a similar decompression product) on the Windows system. If you are familiar with <i>git</i> commands, <tt>git clone</tt> or <tt>git pull</tt> may be used to install ERcore files on the target system as an alternative to the following steps.
</div>
<div class="Indented">
Note that this section covers installing a fresh copy of ERcore on the target system. See Section <a class="Reference" href="#sec:ercore-update-process">12↓</a> for updating ERcore software to a new version.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-7.1">7.1</a> Downloading and decompressing ERcore kit
</h2>
<div class="Unindented">
Perform the following steps to download the ERcore kit to your local Windows system and decompress it:
</div>
<ul>
<li>
Select the appropriate git snapshot from the ERcore repository, as described in Section <a class="Reference" href="#sec:InstallationKits">2↑</a>.
</li>
<li>
Download the ERcore kit ( the <tt>/er/</tt> compressed directory tree) into a local temporary directory
</li>
<li>
Use the 7-ZIP utility to decompress the directory tree.
</li>
<li>
Note that the top-level directory has a generated name similar to <tt>/1837936-bae76ad/</tt> instead of <tt>/er/</tt>. A directory named <tt>/modules/</tt> and a file named <tt>er.module</tt> should exist in this directory.
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-7.2">7.2</a> Removing ERcore from previous install
</h2>
<div class="Unindented">
If ERcore was previously installed on the target system, the following steps should be performed to remove that version from the system:
</div>
<ul>
<li>
login to the target website as administrator
</li>
<li>
click <i>Modules</i> on the Drupal home page
</li>
<li>
scroll down to the EPSCOR section on this page
</li>
<li>
uncheck <i>EPSCoR Reporting</i>
</li>
<li>
click <i>Save configuration</i> at the bottom of the page.
</li>
</ul>
<div class="Unindented">
Next, perform the following steps to remove the /er/ files from target system:
</div>
<ul>
<li>
Use FileZilla to login to the target site.
</li>
<li>
In the FileZilla “remote site” pane, navigate to the <tt><target-modules></tt> directory on the target system.
</li>
<li>
Use FileZilla to delete the contents of the /er/ directory.
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-7.3">7.3</a> Installing ERcore files on target
</h2>
<div class="Unindented">
Perform the following steps to install the ERcore files on the target system:
</div>
<ul>
<li>
Use FileZilla to login to the target site.
</li>
<li>
In the FileZilla “remote site” pane, navigate to the <tt><target-modules></tt> directory on the target system.
</li>
<li>
Create the directory <tt><target-modules>/er/</tt> if it does not yet exist. This is the location where ERcore directory tree will exist on the target system.
</li>
<li>
In the FileZilla “local site” pane, navigate to the top-level directory of the decompressed ERcore kit that was created above. There should be a number of sub-directories and files here including the files <tt>/module/</tt> and <tt>er.module</tt>.
</li>
<li>
Copy the contents of this top-level directory from local site into the <tt><target-modules>/er/</tt> directory on the target system.
</li>
</ul>
<div class="Unindented">
When finished, check that the following files exist at the target site:
</div>
<pre class="LyX-Code">
DOCUMENT_ROOT/sites/all/modules/er/modules/
DOCUMENT_ROOT/sites/all/modules/er/er.module
</pre>
<h1 class="Section">
<a class="toc" name="toc-Section-8">8</a> Step 5: Enable ERcore in Drupal
</h1>
<div class="Unindented">
<a class="Label" name="sec:EnableERcore"> </a>At this point, the ERcore files and all prerequisites should be properly placed on the target. Here we install the ERcore modules within the Drupal framework. Do the following:
</div>
<ul>
<li>
login to the target website as administrator
</li>
<li>
click <i>Modules</i> on the Drupal home page
</li>
<li>
scroll down to the EPSCOR section on this page
</li>
<li>
check <i>EPSCoR Reporting</i>
</li>
<li>
click <i>Save configuration</i> at the bottom of the page.
</li>
<li>
click <i>Continue</i> to the question about if to enable other modules.
</li>
<li>
if you get a question about “rebuild permissions” click <i>Rebuild</i>.
</li>
</ul>
<div class="Unindented">
After several minutes, a status page should appear indicating if installation completed, partially completed, or failed. If installation seems to have completed partially, perform the following steps before trying more elaborate troubleshooting:
</div>
<ul>
<li>
In the EPSCOR section of the Modules page, be sure that <i>EPSCoR Reporting</i> is checked. (This may occur if the Drupal <tt>entityreference</tt> module was not enabled prior to enabling ERcore. See Section .<a class="Reference" href="#sub:DrupalModuleDownload">6.3↑</a>) If <i>EPSCoR Reporting</i> is not checked, check it and click <i>Save configuration</i> again.
</li>
<li>
If this doesn’t work, try unchecking the flag, clicking <i>Save configuration</i>, followed by re-checking the flag and saving again.
</li>
<li>
In some situations “privilege violation” errors from the underlying file system are reported. If this occurs, you may need to modify the file attributes of all files copied to the target such that directories have “<tt>rx</tt>” protections for all users and regular files have “<tt>r</tt>” protection for all users. If this is too difficult with FileZilla, log into the target system and execute the following shell commands:
</li>
</ul>
<pre class="LyX-Code">
cd <target-modules>
find er -type d -exec chmod o+rx {} \;
find er -type f -exec chmod o+r {} \;
</pre>
<div class="Unindented">
Note that the following errors are normal for a typical installation:
</div>
<ul>
<li>
Error: <i>No Institutions found!</i>
</li>
<li>
Error: <i>No Research Components found!</i>
</li>
<li>
Warning: <i>Taxonomy: <field> is extraneous.</i>
</li>
</ul>
<div class="Unindented">
The first two errors indicate initial site configuration data has not been entered yet. This data can be entered after ERcore installation is complete.
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-9">9</a> Step 6: Check installation status and troubleshoot
</h1>
<div class="Unindented">
<a class="Label" name="sec:Check-installation-status"> </a>
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.1">9.1</a> Basic installation status
</h2>
<div class="Unindented">
At this point, ERcore should be installed properly. Check the following to be sure:
</div>
<ul>
<li>
Go to <tt>http://<your-site>/admin/config/epscor/er/status</tt> to view the <i>EPSCoR Reporting Status Report</i> page.
</li>
<li>
Make sure there are no errors shown on this page other than those listed in the previous section. See Section <a class="Reference" href="#sub:ErcoreReset">9.2↓</a> if abnormal errors are found on this page.<br/>
</li>
<li>
click <i>Modules</i>
</li>
<li>
scroll down to the EPSCOR section
</li>
<li>
make sure <i>EPSCoR Reporting</i> is checked<br/>
</li>
<li>
click <i>Reports</i> ▷ <i> Recent log messages</i> (or http://<your-site>/admin/reports/dblog)
</li>
<li>
this shows recent error log messages. look for anything unusual.
</li>
<li>
Note that there may be numerous errors from ERcore in the error log of the form “Unable to attach <xxx> to role <yyy>”. These error may be safely ignored if accompanied by a message of the form “Role <yyy> imported successfully”.
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.2">9.2</a> ERcore installation reset
</h2>
<div class="Unindented">
<a class="Label" name="sub:ErcoreReset"> </a>In cases where installation has partially failed or some other internal error has been detected, the <i>EPSCoR Reporting Status Report</i> page can be used to reset individual ERcore components:
</div>
<ul>
<li>
Go to <tt>http://<your-site>/admin/config/epscor/er/status</tt> to view the <i>EPSCoR Reporting Status Report</i> page.
</li>
<li>
The status of all ERcore components are listed on this page. If there are no errors or warnings, ERcore is installed correctly.
</li>
<li>
If an error is shown for an individual component, click <i>reset</i> to reinitialize that component to ERcore installation-time settings.
</li>
</ul>
<div class="Unindented">
If errors are displayed for several similar components, they may be reset as a group as follows:
</div>
<ul>
<li>
Click <i>BULK RESET</i> on the the <i>EPSCoR Reporting Status Report</i> page to display the available groups for reset: <i>taxonomy</i>, <i>roles</i>, <i>bundles</i>, <i>flags</i>, and <i>rules</i>.
</li>
<li>
Click the desired entry to reset all ERcore components in that group.
</li>
</ul>
<div class="Unindented">
Continue resetting individual components or groups until there are no more errors on the <i>EPSCoR Reporting Status Report</i> page. Performing a Bulk Rest for all ERcore components is essentially the same as reinstalling ERcore.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.3">9.3</a> Apache error log
</h2>
<div class="Unindented">
If you want to be thorough, you can check the Apache error log:
</div>
<ul>
<li>
click <i>Reports</i> ▷ <i> Status report</i> (or http://<your-site>/admin/reports/status)
</li>
<li>
click <i>PHP (more information)</i> (or http://<your-site>/admin/reports/status/php)
</li>
<li>
search for <tt>APACHE_LOG_DIR</tt>
</li>
<li>
this will be the directory where Apache error logs are kept
</li>
<li>
examine the log files in this directory for abnormal events
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.4">9.4</a> Clearing caches
</h2>
<div class="Unindented">
<a class="Label" name="sub:Clearing-caches"> </a>Some problems with Drupal are fixed simply by logging out or flushing caches. This helps to insure that both client and server have identical data. Try any or all of the following:
</div>
<ul>
<li>
logout and log back in to Drupal
</li>
<li>
close browser window on the client machine and start a new session
</li>
<li>
navigate to: <i>Configuration</i> ▷ <i>Development</i> ▷ <i>Performance</i> ▷ <i>Clear all caches</i>
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.5">9.5</a> Double asterisk problem
</h2>
<div class="Unindented">
On some installation, there is a “double asterisk” problem. Check your system for this anomaly as follows:
</div>
<ul>
<li>
click <i>Content ▷ Add Content ▷ Collaboration</i>
</li>
<li>
scroll down to <i>Collaborating Institution/Organization</i>
</li>
</ul>
<div class="Unindented">
If there are two red asterisks instead of one, then the following patch can be applied:
</div>
<ul>
<li>
locate a file named <tt>DOCUMENT_ROOT/misc/states.js</tt> (see Section <a class="Reference" href="#sec:TargetLocation">3↑</a> about <tt>DOCUMENT_ROOT</tt>).
</li>
<li>
[TBA: enter instructions for editing states.js here.]
</li>
</ul>
<div class="Unindented">
More information about the “double asterisk” problem, including a patch, can be found at:
</div>
<ul>
<li>
<a class="URL" href="http://drupal.org/node/1592688">http://drupal.org/node/1592688</a>
</li>
</ul>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-9.6">9.6</a> MySQL server error
</h2>
<div class="Unindented">
Some developers reported receiving PDO errors like "General error: 2006 MySQL server has gone away" which prohibited installation of ERcore. The problem was fixed by adjusting the <tt>max_allowed_packet</tt> size from <tt>1M</tt> to <tt>100M</tt> in the MySQL setup file, <tt>my.ini</tt>. More information about this problem can be found at:
</div>
<ul>
<li>
<a class="URL" href="http://drupal.org/node/1542432">http://drupal.org/node/1542432</a>
</li>
</ul>
<h1 class="Section">
<a class="toc" name="toc-Section-10">10</a> Step 7: Initial ERcore configuration
</h1>
<div class="Unindented">
The menu options should be changed as follows:
</div>
<ul>
<li>
click <i>Modules</i>.
</li>
<li>
scroll down to the Core section.
</li>
<li>
uncheck the <i>Overlay</i> module.
</li>
<li>
uncheck the <i>Toolbar</i> module.
</li>
<li>
scroll down to the Administration section.
</li>
<li>
check the <i>Administration menu Toolbar style</i> module.
</li>
<li>
click <i>Save configuration</i> at the bottom of the page.
</li>
<li>
logout and login again to see these changes.
</li>
</ul>
<div class="Unindented">
In addition, modify these settings at Configuration ▷ Administration ▷ Administration menu:
</div>
<ul>
<li>
check <i>Adjust top margin</i>