forked from ezsystems/ezoracle
-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL
334 lines (232 loc) · 11.8 KB
/
INSTALL
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
eZ Oracle extension [EXTENSION_VERSION] INSTALL
Introduction
============
1. What is the eZ Oracle extension?
--------------------------------
This extension adds support for the Oracle database to eZ Publish by
plugging into the database framework. After it is installed you can
connect to any Oracle database that fits the minimum requirements.
2. License
-------
This software is licensed under the [EXTENSION_LICENSE]. The complete
license agreement is included in the LICENSE file. For more information
or questions please contact info@ez.no
3. Requirements
------------
The following requirements exists for using eZ Oracle extension:
o eZ Publish version:
Make sure you use eZ Publish version [EXTENSION_PUBLISH_VERSION] or higher
together with this extension.
It is generally recommended to always use the latest stable version of
eZ Publish when running on Oracle.
o Oracle version:
Make sure you have Oracle 9, 10 or 11 (client and server).
If the Oracle server version is less than 9.2, setting the environment
variable NLS_LANG is mandatory to indicate that php expects to receive
data from the database in the UTF8 character set.
o PHP with Oracle support (oci8 extension):
Make sure your PHP installation has compiled in support for Oracle. To
compile this you will need the Oracle client libraries and headers.
The standard windows version of php includes the dll needed for oracle support
(but the oracle client is still neded).
To check if Oracle support is enabled, the output of the phpinfo() php
function includes a section titled "oci8". From the command line run `php -i'
o Oracle user with correct privileges:
Make sure you have a user on the oracle server that can create the
following elements: session, table, trigger, sequence and procedure.
Getting eZ Publish
==================
You can download a version of eZ Publish from ez.no, you will find the
various versions at:
http://ez.no/ (enterprise versions)
http://share.ez.no/download-develop (community versions)
NOTE: You will require eZ Publish [EXTENSION_PUBLISH_VERSION] or higher
Information on the installation of eZ Publish can be found at:
http://doc.ez.no/eZ-Publish/Technical-manual/
Restarting Apache
=================
Detailed instructions on the installation and configuration of the oci8
extension are available at http://www.php.net/manual/en/oci8.setup.php.
Possibly you will have to restart the Apache webserver to make sure PHP is
loaded with Oracle support and the needed enviroment variable are in effect.
$ . oraenv
$ apachectl restart
NOTE: Each time you restart the webserver you might need to run the `oraenv'
command, if not the Oracle extension in PHP will not work properly.
Installing eZ Oracle extension
==============================
1. Copy the package into the `extension' directory in the root of your
eZ Publish installation.
2. Unpack the files in the distribution.
$ unzip ezoracle-[EXTENSION_VERSION].zip
3. Enable the extension in eZ Publish. To do this edit site.ini.append.php in the
folder root_of_ezpublish/settings/override. If this file does not exist, create it.
Locate (or add) the block [ExtensionSettings] and add the line:
ActiveExtensions[]=ezoracle
If you run several sites using only one distribution and only some of the sites should use
the extension, make the changes in the override file of that siteaccess.
E.g root_of_ezpublish/settings/siteaccess/news/site.ini.append.php
But instead of using ActiveExtensions you must add these lines instead:
[ExtensionSettings]
ActiveAccessExtensions[]=ezoracle
Regenerate the extension autoload file, either via GUI (in case the eZ Publish
site is already installed ) in the Admin interface, "Setup" tab, "Extensions" page,
or by executing the ezpgenerateautoloads.php file.
Initializing Oracle database
============================
1. Automated install with ora-initialize.sh
----------------------------------------
1. Start from scratch
------------------
If you want to start with a completely new eZ Publish database, go to the
eZ Publish installation directory and run the script:
$ ./extension/ezoracle/bin/shell/ora-initialize.sh
Warning: when using this method, the tables needed by extensions will not
be automatically created.
2. Migrate from an existing database
---------------------------------
To migrate an existing database with its data, you first need to generate
the schema file and the data file with the following commands (launched
from the eZ Publish installation directory):
$ ./bin/php/ezsqldumpschema.php --output-types=schema --format=generic \
--output-array --type=mysql \
--host=<host> --user=<user> --password=<password> \
<database> path/to/schema.dba
$ ./bin/php/ezsqldumpschema.php --output-types=data --format=generic \
--output-array --type=mysql \
--host=<host> --user=<user> --password=<password> \
<database> path/to/data.dba
Then, you can run the ora-initialize.sh script with the previously
generated files in parameter.
$ ./extension/ezoracle/bin/shell/ora-initialize.sh -s path/to/schema.dba \
-d path/to/data.dba
The script will check your system against the requirements. If something
is not as it should be it will give you information on the problem.
The script will ask for some information in some steps, the steps are:
o Testing connection to Oracle server
This step will check if the Oracle server can be connected to using PHP.
Running this step is recommended since it will give information on what
can be done if it fails.
The following information will be asked for:
Username: Which user to connect with
Password: The password for the user
Instance: The name of the oracle instance, this must match the instance
configured on the client. If you are unsure about this you can
use the one set in the ORACLE_SID environment variable.
o Create a new user
This step can create a new user with the required privileges for you.
This is the user that will be the owner of the eZ Publish objects (schema).
If you already have a user with the required privileges you can skip
this step.
o Connecting to Oracle server
This step will read in information which will be used to connect to the
server in later steps. The specified user must have the required
privileges.
Note: This step will be skipped if a user is created in the step above.
Once the script has all necessary information it will connect to the server
and initialize the Oracle database.
o Creating md5_digest and bitor functions
The extension requires custom procedures in the database to handle
md5 strings and bit operations. Your user will require `CREATE PROCEDURE'
privilege for this.
o Cleaning up existing elements in database
If eZ Publish has been previously installed it will remove any elements
left.
o Creating the database schema and inserting data
The schema and data will be taken from the eZ Publish installation files
or from the command line and the database will be initialized with them.
2. Manual install
--------------
Suppose you have a running Oracle instance named "orcl" which you can access
as user "scott" with password "tiger", and you want to run eZ Publish on it.
Here are several steps to achieve this goal:
o Environment variables
Set all the needed environment variables by eg. running `oraenv'.
$ . oraenv
(you may need to consult with your DBA to know which SID to enter)
o Setup a database user:
You must make sure you have a user with the correct privileges
# Here user "system" (DBA) has password "sys".
#################################################################
$ cat <<EOF | sqlplus system/sys@orcl
CREATE USER scott IDENTIFIED BY tiger QUOTA UNLIMITED ON SYSTEM;
GRANT CREATE SESSION TO scott;
GRANT CREATE TABLE TO scott;
GRANT CREATE TRIGGER TO scott;
GRANT CREATE SEQUENCE TO scott;
GRANT CREATE PROCEDURE TO scott;
EOF
#################################################################
You will see "ORA-01920: user name 'SCOTT' conflicts with another user
or role name" if user scott already exists.
If the Oracle server is version 10g or later, new users might be created
with a default tablespace which is not SYSTEM; you should alter the above sql
command accordingly to grant unlimited quota on the correct tablespace
(and possibly specify a customised default tablespace for the user)
o Create md5_digest and bitor functions
The extension requires custom procedures in the database to handle
md5 strings and bit operations. Your user will require `CREATE PROCEDURE'
privilege for this.
$ sqlplus scott/tiger@orcl < extension/ezoracle/sql/md5_digest.sql
$ sqlplus scott/tiger@orcl < extension/ezoracle/sql/bitor.sql
o Initialize the schema
The schema must now be created with all the tables, sequences and
triggers for eZ Publish. Then the schema must be filled with data.
Here you have two choices:
1. Start from scratch
------------------
You can start from scratch by using the schema bundled with the
eZ Publish installation, and filling it with the basic data.
o Import the schema
$ ./bin/php/ezsqlinsertschema.php --type=oracle \
--user=<user> --password=<password> \
--insert-types=schema \
share/db_schema.dba <instance>
o Import the data
$ ./bin/php/ezsqlinsertschema.php --type=oracle \
--user=<user> --password=<password> \
--insert-types=data \
--schema-file=db_data.dba \
share/db_data.dba <instance>
2. Migrate from existing database
------------------------------
If you want/need to migrate an existing database, you can achieve
this with the native eZ Publish tools. Don't forget to add the --siteaccess
parameter if your default siteaccess isn't sufficient information::
o Dump your existing database to the local database.dba file::
$ ./bin/php/ezsqldumpschema.php --output-types=all --format=generic \
--output-array --type=mysql \
--host=<host> --user=<user> --password=<password> \
<database> database.dba
o Insert the dumped data to your oracle database::
$ ./bin/php/ezsqlinsertschema.php --type=oracle \
--user=<user> --password=<password> \
--insert-types=all \
--schema-file=database.dba database.dba <instance>
Configuring eZ Publish
======================
1. Changing eZ Publish database handler
Before eZ Publish will start using the Oracle database, the current
database handler must be changed.
Edit your settings/override/site.ini.append.php and make sure the
DatabaseSettings section contains the following information:
##################################
[DatabaseSettings]
DatabaseImplementation=ezoracle
User=<user>
Password=<password>
Database=<instance>
##################################
You must replace `<user>' `<password>' and `<instance>' with the user and
instance you use to connect to Oracle.
Troubleshooting
===============
1. Read the FAQ
------------
Some problems are more common than others. The most common ones are listed
in the the FAQ.
2. Support
-------
If you have find any problems not handled by this document or the FAQ you
can contact eZ system trough the support system:
http://ez.no/support