git.evergreen-ils.org Git - Evergreen.git/blob - docs/modules/installation/pages/server

1 = Installing the Evergreen server =

2 :toc:

3

4 == Preamble: referenced user accounts ==

5

6 In subsequent sections, we will refer to a number of different accounts, as

7 follows:

8

9 * Linux user accounts:

10 ** The *user* Linux account is the account that you use to log onto the

11 Linux system as a regular user.

12 ** The *root* Linux account is an account that has system administrator

13 privileges. On Debian you can switch to this account from

14 your *user* account by issuing the `su -` command and entering the

15 password for the *root* account when prompted. On Ubuntu you can switch

16 to this account from your *user* account using the `sudo su -` command

17 and entering the password for your *user* account when prompted.

18 ** The *opensrf* Linux account is an account that you create when installing

19 OpenSRF. You can switch to this account from the *root* account by

20 issuing the `su - opensrf` command.

21 ** The *postgres* Linux account is created automatically when you install

22 the PostgreSQL database server. You can switch to this account from the

23 *root* account by issuing the `su - postgres` command.

24 * PostgreSQL user accounts:

25 ** The *evergreen* PostgreSQL account is a superuser account that you will

26 create to connect to the PostgreSQL database server.

27 * Evergreen administrator account:

28 ** The *egadmin* Evergreen account is an administrator account for

29 Evergreen that you will use to test connectivity and configure your

30 Evergreen instance.

31

32 == Preamble: developer instructions ==

33

34 [NOTE]

35 Skip this section if you are using an official release tarball downloaded

36 from http://evergreen-ils.org/egdownloads

37

38 Developers working directly with the source code from the Git repository,

39 rather than an official release tarball, must perform one step before they

40 can proceed with the `./configure` step.

41

42 As the *user* Linux account, issue the following command in the Evergreen

43 source directory to generate the configure script and Makefiles:

44

45 [source, bash]

46 ------------------------------------------------------------------------------

47 autoreconf -i

48 ------------------------------------------------------------------------------

49

50 == Installing prerequisites ==

51

52 * **PostgreSQL**: The minimum supported version is 10.

53 * **Linux**: Evergreen has been tested on

54 Debian Bullseye (11),

55 Debian Buster (10),

56 Debian Stretch (9),

57 Ubuntu Jammy Jellyfish (22.04),

58 Ubuntu Focal Fossa (20.04),

59 and Ubuntu Bionic Beaver (18.04).

60 If you are running an older version of these distributions, you may want

61 to upgrade before upgrading Evergreen. For instructions on upgrading these

62 distributions, visit the Debian or Ubuntu websites.

63 * **OpenSRF**: The minimum supported version of OpenSRF is 3.2.0.

64

65

66 Evergreen has a number of prerequisite packages that must be installed

67 before you can successfully configure, compile, and install Evergreen.

68

69 1. Begin by installing the most recent version of OpenSRF (3.2.0 or later).

70 You can download OpenSRF releases from http://evergreen-ils.org/opensrf-downloads/

71 +

72 2. Issue the following commands as the *root* Linux account to install

73 prerequisites using the `Makefile.install` prerequisite installer,

74 substituting `debian-bullseye`,`debian-buster`,`debian-stretch`,`ubuntu-jammy`,

75 `ubuntu-focal`, or `ubuntu-bionic` for <osname> below:

76 +

77 [source, bash]

78 ------------------------------------------------------------------------------

79 make -f Open-ILS/src/extras/Makefile.install <osname>

80 ------------------------------------------------------------------------------

81 +

82 [[optional_developer_additions]]

83 3. OPTIONAL: Developer additions

84 +

85 To perform certain developer tasks from a Git source code checkout,

86 additional packages are required. As the *root* Linux account:

87 +

88 * To install packages needed for retrieving and managing web dependencies,

89 use the <osname>-developer Makefile.install target. Currently,

90 this is only needed for building and installing the web

91 staff client.

92 * To optionally run Angular and AngularJS tests you will need to manually

93 install Firefox and your choice of Chromium or Chrome.

94 +

95 [source, bash]

96 ------------------------------------------------------------------------------

97 make -f Open-ILS/src/extras/Makefile.install <osname>-developer

98 ------------------------------------------------------------------------------

99 +

100 * To install packages required for building Evergreen translations, use

101 the <osname>-translator Makefile.install target.

102 +

103 [source, bash]

104 ------------------------------------------------------------------------------

105 make -f Open-ILS/src/extras/Makefile.install <osname>-translator

106 ------------------------------------------------------------------------------

107 +

108 * To install packages required for building Evergreen release bundles, use

109 the <osname>-packager Makefile.install target.

110 +

111 [source, bash]

112 ------------------------------------------------------------------------------

113 make -f Open-ILS/src/extras/Makefile.install <osname>-packager

114 ------------------------------------------------------------------------------

115

116 == Extra steps for web staff client ==

117

118 [NOTE]

119 Skip this entire section if you are using an official release tarball downloaded

120 from http://evergreen-ils.org/downloads. Otherwise, ensure you have installed the

121 xref:#optional_developer_additions[optional developer additions] before proceeding.

122

123 [[install_files_for_web_staff_client]]

124 === Install AngularJS files for web staff client ===

125

126 1. Building, Testing, Minification: The remaining steps all take place within

127 the staff JS web root:

128 +

129 [source,sh]

130 ------------------------------------------------------------------------------

131 cd $EVERGREEN_ROOT/Open-ILS/web/js/ui/default/staff/

132 ------------------------------------------------------------------------------

133 +

134 2. Install Project-local Dependencies. npm inspects the 'package.json' file

135 for dependencies and fetches them from the Node package network.

136 +

137 [source,sh]

138 ------------------------------------------------------------------------------

139 npm install # fetch JS dependencies

140 ------------------------------------------------------------------------------

141 +

142 3. Run the build script.

143 +

144 [source,sh]

145 ------------------------------------------------------------------------------

146 npm run build-prod

147 ------------------------------------------------------------------------------

148 +

149 4. OPTIONAL: Test web client code if the <osname>-developer packages and

150 the necessary browsers are installed.

151 CHROME_BIN should be set to the path to chrome or chromimum, e.g.,

152 `/usr/bin/chromium`:

153 +

154 [source,sh]

155 ------------------------------------------------------------------------------

156 CHROME_BIN=/path/to/chrome npm run test

157 ------------------------------------------------------------------------------

158

159 [[install_files_for_angular_web_staff_client]]

160 === Install Angular files for web staff client ===

161

162 1. Building, Testing, Minification: The remaining steps all take place within

163 the Angular staff root:

164 +

165 [source,sh]

166 ------------------------------------------------------------------------------

167 cd $EVERGREEN_ROOT/Open-ILS/src/eg2/

168 ------------------------------------------------------------------------------

169 +

170 2. Install Project-local Dependencies. npm inspects the 'package.json' file

171 for dependencies and fetches them from the Node package network.

172 +

173 [source,sh]

174 ------------------------------------------------------------------------------

175 npm install # fetch JS dependencies

176 ------------------------------------------------------------------------------

177 +

178 3. Run the build script.

179 +

180 [source,sh]

181 ------------------------------------------------------------------------------

182 ng build --prod

183 ------------------------------------------------------------------------------

184 +

185 4. OPTIONAL: Test eg2 web client code if the <osname>-developer packages and

186 the necessary browsers are installed:

187 CHROME_BIN should be set to the path to chrome or chromimum, e.g.,

188 `/usr/bin/chromium`:

189 +

190 [source,sh]

191 ------------------------------------------------------------------------------

192 CHROME_BIN=/path/to/chrome npm run test

193 ------------------------------------------------------------------------------

194

195 [[install_opac_deps]]

196 === Install OPAC skin dependencies ===

197

198 1. The following steps take place within the OPAC dependencies root:

199 +

200 [source,sh]

201 ------------------------------------------------------------------------------

202 cd $EVERGREEN_ROOT/Open-ILS/web/opac/deps

203 ------------------------------------------------------------------------------

204 +

205 2. Install Project-local Dependencies. npm inspects the 'package.json' file

206 for dependencies and fetches them from the Node package network.

207 +

208 [source,sh]

209 ------------------------------------------------------------------------------

210 npm install # fetch JS and CSS dependencies

211 ------------------------------------------------------------------------------

212 +

213 Note that there is no build step.

214

215 == Configuration and compilation instructions ==

216

217 For the time being, we are still installing everything in the `/openils/`

218 directory. From the Evergreen source directory, issue the following commands as

219 the *user* Linux account to configure and build Evergreen:

220

221 [source, bash]

222 ------------------------------------------------------------------------------

223 PATH=/openils/bin:$PATH ./configure --prefix=/openils --sysconfdir=/openils/conf

224 make

225 ------------------------------------------------------------------------------

226

227 These instructions assume that you have also installed OpenSRF under `/openils/`.

228 If not, please adjust PATH as needed so that the Evergreen `configure` script

229 can find `osrf_config`.

230

231 == Installation instructions ==

232

233 1. Once you have configured and compiled Evergreen, issue the following

234 command as the *root* Linux account to install Evergreen and copy

235 example configuration files to `/openils/conf`.

236 +

237 [source, bash]

238 ------------------------------------------------------------------------------

239 make install

240 ------------------------------------------------------------------------------

241

242 == Change ownership of the Evergreen files ==

243

244 All files in the `/openils/` directory and subdirectories must be owned by the

245 `opensrf` user. Issue the following command as the *root* Linux account to

246 change the ownership on the files:

247

248 [source, bash]

249 ------------------------------------------------------------------------------

250 chown -R opensrf:opensrf /openils

251 ------------------------------------------------------------------------------

252

253 == Run ldconfig ==

254

255 On Ubuntu 18.04 / 20.04 / 22.04 or Debian Stretch / Buster / Bullseye, run the

256 following command as the root user:

257

258 [source, bash]

259 ------------------------------------------------------------------------------

260 ldconfig

261 ------------------------------------------------------------------------------

262

263 == Additional Instructions for Developers ==

264

265 [NOTE]

266 Skip this section if you are using an official release tarball downloaded

267 from http://evergreen-ils.org/egdownloads

268

269 Developers working directly with the source code from the Git repository,

270 rather than an official release tarball, need to install the Dojo Toolkit

271 set of JavaScript libraries. The appropriate version of Dojo is included in

272 Evergreen release tarballs. Developers should install the Dojo 1.3.3 version

273 of Dojo by issuing the following commands as the *opensrf* Linux account:

274

275 [source, bash]

276 ------------------------------------------------------------------------------

277 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz

278 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz

279 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.

280 ------------------------------------------------------------------------------

281

282

283 == Configure the Apache Web server ==

284

285 . Use the example configuration files to configure your Web server for

286 the Evergreen catalog, web staff client, Web services, and administration

287 interfaces. Issue the following commands as the *root* Linux account:

288 +

289 [source,bash]

290 ------------------------------------------------------------------------------------

291 cp Open-ILS/examples/apache_24/eg_24.conf /etc/apache2/sites-available/eg.conf

292 cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/apache2/eg_vhost.conf

293 cp Open-ILS/examples/apache_24/eg_startup /etc/apache2/

294 # Now set up SSL

295 mkdir /etc/apache2/ssl

296 cd /etc/apache2/ssl

297 ------------------------------------------------------------------------------------

298 +

299 . The `openssl` command cuts a new SSL key for your Apache server. For a

300 production server, you should purchase a signed SSL certificate, but you can

301 just use a self-signed certificate and accept the warnings in the

302 and browser during testing and development. Create an SSL key for the Apache

303 server by issuing the following command as the *root* Linux account:

304 +

305 [source,bash]

306 ------------------------------------------------------------------------------

307 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key

308 ------------------------------------------------------------------------------

309 +

310 . As the *root* Linux account, edit the `eg.conf` file that you copied into

311 place.

312 a. To enable access to the offline upload / execute interface from any

313 workstation on any network, make the following change (and note that

314 you *must* secure this for a production instance):

315 * Replace `Require host 10.0.0.0/8` with `Require all granted`

316 . Change the user for the Apache server.

317 * As the *root* Linux account, edit

318 `/etc/apache2/envvars`. Change `export APACHE_RUN_USER=www-data` to

319 `export APACHE_RUN_USER=opensrf`.

320 . As the *root* Linux account, configure Apache with KeepAlive settings

321 appropriate for Evergreen. Higher values can improve the performance of a

322 single client by allowing multiple requests to be sent over the same TCP

323 connection, but increase the risk of using up all available Apache child

324 processes and memory.

325 * Edit `/etc/apache2/apache2.conf`.

326 a. Change `KeepAliveTimeout` to `1`.

327 b. Change `MaxKeepAliveRequests` to `100`.

328 . As the *root* Linux account, configure the prefork module to start and keep

329 enough Apache servers available to provide quick responses to clients without

330 running out of memory. The following settings are a good starting point for a

331 site that exposes the default Evergreen catalog to the web:

332 +

333 .`/etc/apache2/mods-available/mpm_prefork.conf`

334 [source,bash]

335 ------------------------------------------------------------------------------

336 <IfModule mpm_prefork_module>

337 StartServers 15

338 MinSpareServers 5

339 MaxSpareServers 15

340 MaxRequestWorkers 75

341 MaxConnectionsPerChild 500

342 </IfModule>

343 ------------------------------------------------------------------------------

344 +

345 . As the *root* user, enable the mpm_prefork module:

346 +

347 [source,bash]

348 ------------------------------------------------------------------------------

349 a2dismod mpm_event

350 a2enmod mpm_prefork

351 ------------------------------------------------------------------------------

352 +

353 . As the *root* Linux account, enable the Evergreen site:

354 +

355 [source,bash]

356 ------------------------------------------------------------------------------

357 a2dissite 000-default # OPTIONAL: disable the default site (the "It Works" page)

358 a2ensite eg.conf

359 ------------------------------------------------------------------------------

360 +

361 . As the *root* Linux account, enable Apache to write

362 to the lock directory; this is currently necessary because Apache

363 is running as the `opensrf` user:

364 +

365 [source,bash]

366 ------------------------------------------------------------------------------

367 chown opensrf /var/lock/apache2

368 ------------------------------------------------------------------------------

369

370 Learn more about additional Apache options in the following sections:

371

372 * xref:admin:apache_rewrite_tricks.adoc#apache_rewrite_tricks[Apache Rewrite Tricks]

373 * xref:admin:apache_access_handler.adoc#apache_access_handler_perl_module[Apache Access Handler Perl Module]

374

375 == Configure OpenSRF for the Evergreen application ==

376

377 There are a number of example OpenSRF configuration files in `/openils/conf/`

378 that you can use as a template for your Evergreen installation. Issue the

379 following commands as the *opensrf* Linux account:

380

381 [source, bash]

382 ------------------------------------------------------------------------------

383 cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml

384 cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml

385 ------------------------------------------------------------------------------

386

387 When you installed OpenSRF, you created four Jabber users on two

388 separate domains and edited the `opensrf_core.xml` file accordingly. Please

389 refer back to the OpenSRF README and, as the *opensrf* Linux account, edit the

390 Evergreen version of the `opensrf_core.xml` file using the same Jabber users

391 and domains as you used while installing and testing OpenSRF.

392

393 [NOTE]

394 The `-b` flag tells the `cp` command to create a backup version of the

395 destination file. The backup version of the destination file has a tilde (`~`)

396 appended to the file name, so if you have forgotten the Jabber users and

397 domains, you can retrieve the settings from the backup version of the files.

398

399 `eg_db_config`, described in xref:#creating_the_evergreen_database[Creating the Evergreen database], sets the database connection information in `opensrf.xml` for you.

400

401 === Configure action triggers for the Evergreen application ===

402 _Action Triggers_ provide hooks for the system to perform actions when a given

403 event occurs; for example, to generate reminder or overdue notices, the

404 `checkout.due` hook is processed and events are triggered for potential actions

405 if there is no checkin time.

406

407 To enable the default set of hooks, issue the following command as the

408 *opensrf* Linux account:

409

410 [source, bash]

411 ------------------------------------------------------------------------------

412 cp -b /openils/conf/action_trigger_filters.json.example /openils/conf/action_trigger_filters.json

413 ------------------------------------------------------------------------------

414

415 For more information about configuring and running action triggers, see

416 xref:admin:actiontriggers_process.adoc#processing_action_triggers[Notifications / Action Triggers].

417

418 [[creating_the_evergreen_database]]

419 == Creating the Evergreen database ==

420

421 === Setting up the PostgreSQL server ===

422

423 For production use, most libraries install the PostgreSQL database server on a

424 dedicated machine. Therefore, by default, the `Makefile.install` prerequisite

425 installer does *not* install the PostgreSQL database server that is required

426 by every Evergreen system. You can install the packages required by Debian or

427 Ubuntu on the machine of your choice using the following commands as the

428 *root* Linux account:

429

430 . Installing PostgreSQL server packages

431

432 Each OS build target provides the postgres server installation

433 packages required for each operating system. To install Postgres

434 server packages, use the make target

435 'postgres-server-<OSTYPE>-<POSTGRESVERSION>'. Choose the most

436 appropriate command below based on your operating system and desired

437 PostgreSQL Version.

438

439 The first below will install PostgreSQL 10, the minimum supported

440 version and the version recommended for production use of Evergreen:

441

442 [source, bash]

443 ------------------------------------------------------------------------------

444 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-bullseye-10

445 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-buster-10

446 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-stretch-10

447 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-bionic-10

448 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-focal-10

449 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-jammy-10

450 ------------------------------------------------------------------------------

451

452 [WARNING]

453 =========

454 Evergreen support for PostgreSQL server versions greater than 10 is

455 still exprimental. The use of the following is discouraged in

456 production environments. The following are only recommended if you

457 are willing to test newer PostgreSQL versions for performance and

458 possible bugs.

459 =========

460

461 To install PostgreSQL version 11, use the following command for your operating

462 system:

463

464 [source, bash]

465 ------------------------------------------------------------------------------

466 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-bullseye-11

467 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-buster-11

468 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-stretch-11

469 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-bionic-11

470 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-focal-11

471 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-jammy-11

472 ------------------------------------------------------------------------------

473

474 To install PostgreSQL version 12, use the following command for your operating

475 system:

476

477 [source, bash]

478 ------------------------------------------------------------------------------

479 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-bullseye-12

480 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-buster-12

481 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-stretch-12

482 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-bionic-12

483 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-focal-12

484 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-jammy-12

485 ------------------------------------------------------------------------------

486

487 To install PostgreSQL version 13, use the following command for your operating

488 system:

489

490 [source, bash]

491 ------------------------------------------------------------------------------

492 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-bullseye-13

493 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-buster-13

494 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-stretch-13

495 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-bionic-13

496 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-focal-13

497 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-jammy-13

498 ------------------------------------------------------------------------------

499

500 To install PostgreSQL version 14, use the following command for your operating

501 system:

502

503 [source, bash]

504 ------------------------------------------------------------------------------

505 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-bullseye-14

506 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-buster-14

507 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-stretch-14

508 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-bionic-14

509 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-focal-14

510 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-jammy-14

511 ------------------------------------------------------------------------------

512

513 For a standalone PostgreSQL server, install the following Perl modules for your

514 distribution as the *root* Linux account:

515

516 .(Debian and Ubuntu)

517 No extra modules required for these distributions.

518

519 You need to create a PostgreSQL superuser to create and access the database.

520 Issue the following command as the *postgres* Linux account to create a new

521 PostgreSQL superuser named `evergreen`. When prompted, enter the new user's

522 password:

523

524 [source, bash]

525 ------------------------------------------------------------------------------

526 createuser -s -P evergreen

527 ------------------------------------------------------------------------------

528

529 .Enabling connections to the PostgreSQL database

530

531 Your PostgreSQL database may be configured by default to prevent connections,

532 for example, it might reject attempts to connect via TCP/IP or from other

533 servers. To enable TCP/IP connections from localhost, check your `pg_hba.conf`

534 file, found in the `/etc/postgresql/` directory on Debian and Ubuntu.

535 A simple way to enable TCP/IP

536 connections from localhost to all databases with password authentication, which

537 would be suitable for a test install of Evergreen on a single server, is to

538 ensure the file contains the following entries _before_ any "host ... ident"

539 entries:

540

541 ------------------------------------------------------------------------------

542 host all all ::1/128 md5

543 host all all 127.0.0.1/32 md5

544 ------------------------------------------------------------------------------

545

546 When you change the `pg_hba.conf` file, you will need to reload PostgreSQL to

547 make the changes take effect. For more information on configuring connectivity

548 to PostgreSQL, see

549 http://www.postgresql.org/docs/devel/static/auth-pg-hba-conf.html

550

551 === Creating the Evergreen database and schema ===

552

553 Once you have created the *evergreen* PostgreSQL account, you also need to

554 create the database and schema, and configure your configuration files to point

555 at the database server. Issue the following command as the *root* Linux account

556 from inside the Evergreen source directory, replacing <user>, <password>,

557 <hostname>, <port>, and <dbname> with the appropriate values for your

558 PostgreSQL database (where <user> and <password> are for the *evergreen*

559 PostgreSQL account you just created), and replace <admin-user> and <admin-pass>

560 with the values you want for the *egadmin* Evergreen administrator account:

561

562 [source, bash]

563 ------------------------------------------------------------------------------

564 perl Open-ILS/src/support-scripts/eg_db_config --update-config \

565 --service all --create-database --create-schema --create-offline \

566 --user <user> --password <password> --hostname <hostname> --port <port> \

567 --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>

568 ------------------------------------------------------------------------------

569

570 This creates the database and schema and configures all of the services in

571 your `/openils/conf/opensrf.xml` configuration file to point to that database.

572 It also creates the configuration files required by the Evergreen `cgi-bin`

573 administration scripts, and sets the user name and password for the *egadmin*

574 Evergreen administrator account to your requested values.

575

576 You can get a complete set of options for `eg_db_config` by passing the

577 `--help` parameter.

578

579 === Loading sample data ===

580

581 If you add the `--load-all-sample` parameter to the `eg_db_config` command,

582 a set of authority and bibliographic records, call numbers, copies, staff

583 and regular users, and transactions will be loaded into your target

584 database. This sample dataset is commonly referred to as the _concerto_

585 sample data, and can be useful for testing out Evergreen functionality and

586 for creating problem reports that developers can easily recreate with their

587 own copy of the _concerto_ sample data.

588

589 === Creating the database on a remote server ===

590

591 In a production instance of Evergreen, your PostgreSQL server should be

592 installed on a dedicated server.

593

594 To create the database instance on a remote database server, simply

595 use the `--create-database` flag on `eg_db_config`.

596

597 == Starting Evergreen ==

598

599 1. As the *root* Linux account, start the `memcached` and `ejabberd` services

600 (if they aren't already running):

601 +

602 [source, bash]

603 ------------------------------------------------------------------------------

604 /etc/init.d/ejabberd start

605 /etc/init.d/memcached start

606 ------------------------------------------------------------------------------

607 +

608 2. As the *opensrf* Linux account, start Evergreen. The `-l` flag in the

609 following command is only necessary if you want to force Evergreen to treat the

610 hostname as `localhost`; if you configured `opensrf.xml` using the real

611 hostname of your machine as returned by `perl -ENet::Domain 'print

612 Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag.

613 +

614 [source, bash]

615 ------------------------------------------------------------------------------

616 osrf_control -l --start-all

617 ------------------------------------------------------------------------------

618 +

619 ** If you receive the error message `bash: osrf_control: command not found`,

620 then your environment variable `PATH` does not include the `/openils/bin`

621 directory; this should have been set in the *opensrf* Linux account's

622 `.bashrc` configuration file. To manually set the `PATH` variable, edit the

623 configuration file `~/.bashrc` as the *opensrf* Linux account and add the

624 following line:

625 +

626 [source, bash]

627 ------------------------------------------------------------------------------

628 export PATH=$PATH:/openils/bin

629 ------------------------------------------------------------------------------

630 +

631 3. As the *opensrf* Linux account, generate the Web files needed by the web staff

632 client and catalog and update the organization unit proximity (you need to do

633 this the first time you start Evergreen, and after that each time you change the library org unit configuration.

634 ):

635 +

636 [source, bash]

637 ------------------------------------------------------------------------------

638 autogen.sh

639 ------------------------------------------------------------------------------

640 +

641 4. As the *root* Linux account, restart the Apache Web server:

642 +

643 [source, bash]

644 ------------------------------------------------------------------------------

645 /etc/init.d/apache2 restart

646 ------------------------------------------------------------------------------

647 +

648 If the Apache Web server was running when you started the OpenSRF services, you

649 might not be able to successfully log in to the OPAC or web staff client until the

650 Apache Web server is restarted.

651

652 == Testing connections to Evergreen ==

653

654 Once you have installed and started Evergreen, test your connection to

655 Evergreen via `srfsh`. As the *opensrf* Linux account, issue the following

656 commands to start `srfsh` and try to log onto the Evergreen server using the

657 *egadmin* Evergreen administrator user name and password that you set using the

658 `eg_db_config` command:

659

660 [source, bash]

661 ------------------------------------------------------------------------------

662 /openils/bin/srfsh

663 srfsh% login <admin-user> <admin-pass>

664 ------------------------------------------------------------------------------

665

666 You should see a result like:

667

668 Received Data: "250bf1518c7527a03249858687714376"

669 ------------------------------------

670 Request Completed Successfully

671 Request Time in seconds: 0.045286

672 ------------------------------------

673

674 Received Data: {

675 "ilsevent":0,

676 "textcode":"SUCCESS",

677 "desc":" ",

678 "pid":21616,

679 "stacktrace":"oils_auth.c:304",

680 "payload":{

681 "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",

682 "authtime":420

683 }

684

685 }

686

687 ------------------------------------

688 Request Completed Successfully

689 Request Time in seconds: 1.336568

690 ------------------------------------

691 [[install-troubleshooting-1]]

692 If this does not work, it's time to do some troubleshooting.

693

694 * As the *opensrf* Linux account, run the `settings-tester.pl` script to see

695 if it finds any system configuration problems. The script is found at

696 `Open-ILS/src/support-scripts/settings-tester.pl` in the Evergreen source

697 tree.

698 * Follow the steps in the http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[troubleshooting guide].

699 * If you have faithfully followed the entire set of installation steps

700 listed here, you are probably extremely close to a working system.

701 Gather your configuration files and log files and contact the

702 http://evergreen-ils.org/communicate/mailing-lists/[Evergreen development

703 mailing list] for assistance before making any drastic changes to your system

704 configuration.

705

706 == Getting help ==

707

708 Need help installing or using Evergreen? Join the mailing lists at

709 http://evergreen-ils.org/communicate/mailing-lists/ or contact us on the Freenode

710 IRC network on the #evergreen channel.

711

712 == License ==

713

714 This work is licensed under the Creative Commons Attribution-ShareAlike 3.0

715 Unported License. To view a copy of this license, visit

716 http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative

717 Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.