From 21ab8e25595faf24bfc413611f7e3a52497c140d Mon Sep 17 00:00:00 2001 From: Dan Scott Date: Wed, 5 Oct 2011 13:12:30 -0400 Subject: [PATCH] README: Explicitly identify accounts for commands Add a preamble to the beginning listing all of the accounts referenced in the instructions (Linux accounts, PostgreSQL accounts, Evergreen administrator accounts). Also move the Developer Instructions to the start to follow the natural order of operations. Signed-off-by: Dan Scott --- README | 266 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 153 insertions(+), 113 deletions(-) diff --git a/README b/README index 108fb0ba20..d0f8b2e00b 100644 --- a/README +++ b/README @@ -1,6 +1,73 @@ README for Evergreen master =========================== +Preamble: referenced user accounts +---------------------------------- + +In subsequent sections, we will refer to a number of different accounts, as +follows: + + * Linux user accounts: + ** The *user* Linux account is the account that you use to log onto the + Linux system as a regular user. + ** The *root* Linux account is an account that has system administrator + privileges. On Debian and Fedora you can switch to this account from + your *user* account by issuing the `su -` command and entering the + password for the *root* account when prompted. On Ubuntu you can switch + to this account from your *user* account using the `sudo su -` command + and entering the password for your *user* account when prompted. + ** The *opensrf* Linux account is an account that you create when installing + OpenSRF. You can switch to this account from the *root* account by + issuing the `su - opensrf` command. + ** The *postgres* Linux account is created automatically when you install + the PostgreSQL database server. You can switch to this account from the + *root* account by issuing the `su - opensrf` command. + * PostgreSQL user accounts: + ** The *evergreen* PostgreSQL account is a superuser account that you will + create to connect to the PostgreSQL database server. + * Evergreen administrator account: + ** The *egadmin* Evergreen account is an administrator account for + Evergreen that you will use to test connectivity and configure your + Evergreen instance. + +Preamble: Developer instructions +-------------------------------- + +[NOTE] +Skip this section if you are using an official release tarball downloaded +from http://evergreen-ils.org/downloads + +Developers working directly with the source code from the Git repository, +rather than an official release tarball, must install some extra packages +and perform one step before they can proceed with the `./configure` step. + +As the *root* Linux account, install the following packages: + + * autoconf + * automake + * libtool + +As the *user* Linux account, issue the following command in the Evergreen +source directory to generate the configure script and Makefiles: + +[source, bash] +------------------------------------------------------------------------------ +./autogen.sh +------------------------------------------------------------------------------ + +After running `make install`, developers also need to install the Dojo Toolkit +set of JavaScript libraries. The appropriate version of Dojo is included +in Evergreen release tarballs. Developers should install the Dojo 1.3.3 +version of Dojo by issuing the following commands as the *opensrf* Linux +account: + +[source, bash] +------------------------------------------------------------------------------ +wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz +tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz +cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/. +------------------------------------------------------------------------------ + Installing prerequisites: ------------------------- @@ -8,18 +75,20 @@ Evergreen has a number of prerequisite packages that must be installed before you can successfully configure, compile, and install Evergreen. 1. Begin by installing the most recent version of OpenSRF (2.0 or later). - You can download OpenSRF releases from http://evergreen-ils.org/downloads + You can download OpenSRF releases from http://evergreen-ils.org/opensrf.php 2. On many distributions, it is necessary to install PostgreSQL 9 from external repositories. + - * On Debian Squeeze, add the following line to `/etc/apt/sources.list`: + * On Debian Squeeze, open `/etc/apt/sources.list` in a text editor as the + *root* Linux account and add the following line: + [source, bash] ------------------------------------------------------------------------------ deb http://backports.debian.org/debian-backports squeeze-backports main contrib ------------------------------------------------------------------------------ + - * On Ubuntu Lucid, add the following line to `/etc/apt/sources.list`: + * On Ubuntu Lucid, open `/etc/apt/sources.list` in a text editor as the + *root* Linux account and add the following line: + [source, bash] ------------------------------------------------------------------------------ @@ -28,14 +97,11 @@ deb http://archive.ubuntu.com/ubuntu lucid-backports main universe multiverse re + * Fedora 15 comes with PostgreSQL 9, so no additional steps are required. + -3. On Debian and Ubuntu, run `aptitude update` to retrieve the new packages - from the backports repository. -4. On Debian and Ubuntu, the easiest way to install the rest of the - prerequisites for Evergreen is to use the Makefile.install prerequisite - installer. -5. Issue the following commands as the root user to install prerequisites - using the Makefile.install prerequisite installer, substituting - `debian-squeeze`, `fedora15`, `ubuntu-lucid`, `centos`, or +3. On Debian and Ubuntu, run `aptitude update` as the *root* Linux account to + retrieve the new packages from the backports repository. +4. Issue the following commands as the *root* Linux account to install + prerequisites using the `Makefile.install` prerequisite installer, + substituting `debian-squeeze`, `fedora15`, `ubuntu-lucid`, `centos`, or `rhel` for below: + [source, bash] @@ -43,12 +109,13 @@ deb http://archive.ubuntu.com/ubuntu lucid-backports main universe multiverse re make -f Open-ILS/src/extras/Makefile.install ------------------------------------------------------------------------------ + -Note: `centos` and `rhel` are less tested than the `debian`, `fedora`, +[NOTE] +`centos` and `rhel` are less tested than the `debian`, `fedora`, and `ubuntu` options. Your patches and suggestions for improvement are welcome! + -6. Add the libdbi-libdbd libraries to the system dynamic library path by - issuing the following commands as the root user: +5. Add the libdbi-libdbd libraries to the system dynamic library path by + issuing the following commands as the *root* Linux account: + .Debian / Ubuntu [source, bash] @@ -68,11 +135,8 @@ Configuration and compilation instructions: ------------------------------------------- For the time being, we are still installing everything in the `/openils/` -directory. If you are working with a version of Evergreen taken directly -from the Git repository, rather than a packaged version of Evergreen, -first see `Developer instructions` below. - -Otherwise, issue the following commands to configure and build Evergreen: +directory. From the Evergreen source directory, issue the following commands as +the *user* Linux account to configure and build Evergreen: [source, bash] ------------------------------------------------------------------------------ @@ -84,8 +148,9 @@ Installation instructions: -------------------------- 1. Once you have configured and compiled Evergreen, issue the following - command as the root user to install Evergreen, build the server portion of - the staff client, and copy example configuration files to `/openils/conf`. + command as the *root* Linux account to install Evergreen, build the server + portion of the staff client, and copy example configuration files to + `/openils/conf`. Change the value of the `STAFF_CLIENT_STAMP_ID` variable to match the version of the staff client that you will use to connect to the Evergreen server. + @@ -95,9 +160,10 @@ make STAFF_CLIENT_STAMP_ID=rel_name install ------------------------------------------------------------------------------ + 2. The server portion of the staff client expects `http://hostname/xul/server` - to resolve. The following command creates a symbolic link pointing to the - `server` subdirectory of the server portion of the staff client that we just - built using the staff client ID 'rel_name': + to resolve. Issue the following commands as the *root* Linux account to + create a symbolic link pointing to the `server` subdirectory of the server + portion of the staff client that we just built using the staff client ID + 'rel_name': + [source, bash] ------------------------------------------------------------------------------ @@ -109,8 +175,8 @@ Change ownership of the Evergreen files: ---------------------------------------- All files in the `/openils/` directory and subdirectories must be owned by the -`opensrf` user. Issue the following command as the root user to change the -ownership on the files: +`opensrf` user. Issue the following command as the *root* Linux account to +change the ownership on the files: [source, bash] ------------------------------------------------------------------------------ @@ -120,9 +186,10 @@ chown -R opensrf:opensrf /openils Configure the Apache Web server: -------------------------------- -1. Use the example configuration files in `Open-ILS/examples/apache/` to configure -your Web server for the Evergreen catalog, staff client, Web services, and -administration interfaces. +1. Use the example configuration files in `Open-ILS/examples/apache/` to +configure your Web server for the Evergreen catalog, staff client, Web +services, and administration interfaces. Issue the following commands as the +*root* Linux account: + .Debian and Ubuntu [source,bash] @@ -146,31 +213,32 @@ mkdir /etc/httpd/ssl cd /etc/httpd/ssl ------------------------------------------------------------------------------ + -2. Create an SSL key for the Apache server: +2. The `openssl` command cuts a new SSL key for your Apache server. For a +production server, you should purchase a signed SSL certificate, but you can +just use a self-signed certificate and accept the warnings in the staff client +and browser during testing and development. Create an SSL key for the Apache +server by issuing the following command as the *root* Linux account: + [source,bash] ------------------------------------------------------------------------------ openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key ------------------------------------------------------------------------------ + -The `openssl` command cuts a new SSL key for your Apache server. For a -production server, you should purchase a signed SSL certificate, but you can -just use a self-signed certificate and accept the warnings in the staff client -and browser during testing and development -+ -3. Edit the `eg.conf` file that you copied into place. +3. As the *root* Linux account, edit the `eg.conf` file that you copied into +place. a. Replace `Allow from 10.0.0.0/8` with `Allow from all` (to enable access to the offline upload / execute interface from any workstation on any network - note that you must secure this for a production instance) 4. Change the user for the Apache server. - * (Debian and Ubuntu): As the root user, edit `/etc/apache2/envvars`. - Change `export APACHE_RUN_USER=www-data` to + * (Debian and Ubuntu): As the *root* Linux account, edit + `/etc/apache2/envvars`. Change `export APACHE_RUN_USER=www-data` to `export APACHE_RUN_USER=opensrf`. - * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`. Change - `User apache` to `User opensrf`. + * (Fedora): As the *root* Linux account , edit `/etc/httpd/conf/httpd.conf`. + Change `User apache` to `User opensrf`. 5. Configure Apache with performance settings appropriate for Evergreen: - * (Debian and Ubuntu): As the root user, edit `/etc/apache2/apache2.conf`: - * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`: + * (Debian and Ubuntu): As the *root* Linux account, edit + `/etc/apache2/apache2.conf`: + * (Fedora): As the *root* Linux account, edit `/etc/httpd/conf/httpd.conf`: a. Change `KeepAliveTimeout` to `1`. Higher values reduce the chance of a request timing out unexpectedly, but increase the risk of using up all available Apache child processes. @@ -189,7 +257,7 @@ and browser during testing and development ------------------------------------------------------------------------------ + -6. (Debian and Ubuntu): As the root user, enable the Evergreen site: +6. (Debian and Ubuntu): As the *root* Linux account, enable the Evergreen site: + [source,bash] ------------------------------------------------------------------------------ @@ -200,7 +268,8 @@ a2ensite eg.conf Configure OpenSRF for the Evergreen application: ------------------------------------------------ There are a number of example OpenSRF configuration files in `/openils/conf/` -that you can use as a template for your Evergreen installation. +that you can use as a template for your Evergreen installation. Issue the +following commands as the *opensrf* Linux account: [source, bash] ------------------------------------------------------------------------------ @@ -210,9 +279,9 @@ cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml When you installed OpenSRF, you created four Jabber users on two separate domains and edited the `opensrf_core.xml` file accordingly. Please -refer back to the OpenSRF README and edit the Evergreen version of the -`opensrf_core.xml` file using the same Jabber users and domains as you used -while installing and testing OpenSRF. +refer back to the OpenSRF README and, as the *opensrf* Linux account, edit the +Evergreen version of the `opensrf_core.xml` file using the same Jabber users +and domains as you used while installing and testing OpenSRF. `eg_db_config.pl`, described in the following section, sets the database connection information in `opensrf.xml` for you. @@ -224,7 +293,8 @@ By default, the `Makefile.install` prerequisite installer does not install the PostgreSQL 9.0 database server required by every Evergreen system; for production use, most libraries install the PostgreSQL database server on a dedicated machine. You can install the packages required by Debian, Ubuntu, or -Fedora on the machine of your choice using the following commands: +Fedora on the machine of your choice using the following commands as the *root* +Linux account: .(Debian / Ubuntu) Installing PostgreSQL 9.0 server packages [source, bash] @@ -239,7 +309,7 @@ make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server ------------------------------------------------------------------------------ For a standalone PostgreSQL server, install the following Perl modules as the -root user: +*root* Linux account: .(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9.0 server [source, bash] @@ -265,22 +335,23 @@ cpan UUID::Tiny ------------------------------------------------------------------------------ You need to create a PostgreSQL superuser to create and access the database. -Issue the following command as the `postgres` user to create a new PostgreSQL -superuser named `evergreen`. When prompted, enter the new user's password: +Issue the following command as the *postgres* Linux account to create a new +PostgreSQL superuser named `evergreen`. When prompted, enter the new user's +password: [source, bash] ------------------------------------------------------------------------------ createuser -s -P evergreen ------------------------------------------------------------------------------ -Once you have created the Evergreen superuser, you also need to create the -database and schema, and configure your configuration files to point at the -database server. Issue the following command as root from inside the Evergreen -source directory, replacing , , , , and -with the appropriate values for your PostgreSQL database (where and - are for the PostgreSQL superuser you just created), and replace - and with the values you want for the default -Evergreen administrator account: +Once you have created the *evergreen* PostgreSQL account, you also need to +create the database and schema, and configure your configuration files to point +at the database server. Issue the following command as the *root* Linux account +from inside the Evergreen source directory, replacing , , +, , and with the appropriate values for your +PostgreSQL database (where and are for the *evergreen* +PostgreSQL account you just created), and replace and +with the values you want for the *egadmin* Evergreen administrator account: [source, bash] ------------------------------------------------------------------------------ @@ -292,8 +363,8 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ This creates the database and schema and configures all of the services in your `/openils/conf/opensrf.xml` configuration file to point to that database. -It also creates the configuration files required by the Evergreen cgi-bin -administration scripts, and sets the user name and password for the default +It also creates the configuration files required by the Evergreen `cgi-bin` +administration scripts, and sets the user name and password for the *egadmin* Evergreen administrator account to your requested values. Creating the database on a remote server @@ -306,7 +377,7 @@ can either: are installing the Evergreen code, and use the --create-database option from that machine, or * Copy the `Open-ILS/src/sql/Pg/create-database.sql` script to your - PostgreSQL server and invoke it with: + PostgreSQL server and invoke it as the *postgres* Linux account: + [source, bash] ------------------------------------------------------------------------------ @@ -317,42 +388,10 @@ Then you can issue the `eg_db_config.pl` command as above _without_ the `--create-database` argument to create your schema and configure your configuration files. -Developer instructions: ------------------------ - -Developers working directly with the source code from the Git -repository must also install some extra packages and perform -one more step before they can proceed with the `./configure` step. - -Install the following packages: - - * autoconf - * automake - * libtool - -Run the following command in the source directory to generate the configure -script and Makefiles: - -[source, bash] ------------------------------------------------------------------------------- -./autogen.sh ------------------------------------------------------------------------------- - -After running `make install`, developers also need to install the Dojo Toolkit -set of JavaScript libraries. The appropriate version of Dojo is included -in Evergreen release tarballs; developers should install the Dojo 1.3.3 -version of Dojo as follows: - -[source, bash] ------------------------------------------------------------------------------- -wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz -tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz -cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/. ------------------------------------------------------------------------------- - Starting Evergreen ------------------ -1. As the root user, start the `memcached` and `ejabberd` services (if they aren't already running): +1. As the *root* Linux account, start the `memcached` and `ejabberd` services +(if they aren't already running): + [source, bash] ------------------------------------------------------------------------------ @@ -360,10 +399,10 @@ Starting Evergreen /etc/init.d/memcached start ------------------------------------------------------------------------------ + -2. As the opensrf user, start Evergreen. The `-l` flag in the following command -is only necessary if you want to force Evergreen to treat the hostname as -`localhost`; if you configured `opensrf.xml` using the real hostname -of your machine as returned by `perl -ENet::Domain 'print +2. As the *opensrf* Linux account, start Evergreen. The `-l` flag in the +following command is only necessary if you want to force Evergreen to treat the +hostname as `localhost`; if you configured `opensrf.xml` using the real +hostname of your machine as returned by `perl -ENet::Domain 'print Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag. + [source, bash] @@ -373,27 +412,27 @@ osrf_ctl.sh -l -a start_all + ** If you receive the error message `bash: osrf_ctl.sh: command not found`, then your environment variable `PATH` does not include the `/openils/bin` - directory; this should have been set in the opensrf user's `.bashrc` - configuration file. To manually set the `PATH` variable, edit the - configuration file `~/.bashrc` as the opensrf user and add the following - line: + directory; this should have been set in the *opensrf* Linux account's + `.bashrc` configuration file. To manually set the `PATH` variable, edit the + configuration file `~/.bashrc` as the *opensrf* Linux account and add the + following line: + [source, bash] ------------------------------------------------------------------------------ export PATH=$PATH:/openils/bin ------------------------------------------------------------------------------ + -3. As the `opensrf` user, generate the Web files needed by the staff client - and catalogue and update the organization unit proximity (you need to do - this the first time you start Evergreen, and after that each time you - change the library hierarchy in `config.cgi`): +3. As the *opensrf* Linux account, generate the Web files needed by the staff + client and catalogue and update the organization unit proximity (you need to do + this the first time you start Evergreen, and after that each time you change + the library hierarchy in `config.cgi`): + [source, bash] ------------------------------------------------------------------------------ autogen.sh -u ------------------------------------------------------------------------------ + -4. As the `root` user, restart the Apache Web server: +4. As the *root* Linux account, restart the Apache Web server: + [source, bash] ------------------------------------------------------------------------------ @@ -408,8 +447,9 @@ Testing connections to Evergreen -------------------------------- Once you have installed and started Evergreen, test your connection to -Evergreen via `srfsh`. Start `srfsh` and try to log onto the Evergreen server -using the administrator user name and password that you set using the +Evergreen via `srfsh`. As the *opensrf* Linux account, issue the following +commands to start `srfsh` and try to log onto the Evergreen server using the +*egadmin* Evergreen administrator user name and password that you set using the `eg_db_config.pl` command: [source, bash] @@ -446,8 +486,8 @@ You should see a result like: If this does not work, it's time to do some troubleshooting. - * As the opensrf user, run the `settings-tester.pl` script to see if it - finds any system configuration problems. The script is found at + * As the *opensrf* Linux acccount, run the `settings-tester.pl` script to see + if it finds any system configuration problems. The script is found at `Open-ILS/src/support-scripts/settings-tester.pl` in the Evergreen source tree. * Follow the steps in the http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[troubleshooting guide]. -- 2.43.2