Adobe Content Server 4 (ACS4) Setup Guide

http://webdevlogs.blogspot.com/2009/02/adobe-content-server-4-acs4-setup-guide.html

Content Server Help and Support

http://www.adobe.com/support/contentserver/

Adobe Content Server 4 (ACS4) Setup Guide

This setup guide is written for a single server installation, using Apache, MySQL and PHP to

keep things simple.

I make no excuses that i borrowed a lot of content from the original Adobe Content Server

4 Technical Reference Manuals and other Documentation while adding in my personal

notes, screen shots, and potential pitfalls to look out for.

Read through everything you can before beginning the setup process, understanding the

concept of Adobe Content Server as a whole is as important as getting everything running

smoothly.

Please refer to, study, and read the original ACS4 installation and quick start

documentation here.

The ACS4 installation can be split into steps:

Installing the basic requirements

Setting up the Admin console

Setting up the Fulfillment service

Setting up the Packaging service

Generating the Certificate files

Completing Config Files

Content Server Status Checks

Book Packaging and Distribution

Serving the Sample Store

You may wish to have the packaging service and media storage on seperate machines to

distribute workloads.

Basic requirements to run Adobe Content Server:

The Java Runtime Environment (JRE)

Apache Tomcat version 6 or higher

MySQL version 5 or higher.

In addition, to run an online store, you will also need: 

Apache HTTP Server

PHP 5 or above.

I will not be covering the installation of the basic requirements to run ACS4, please refer to

specific vendor installation instructions for each required component.

Install the Java Runtime Environment (JRE) first as Apache Tomcat will need to know the

install path of the JRE when we set it up.

The JRE can be obtained here.

Next install the Apache HTTP Server, and PHP

By default Apache HTTP Server will run on port 80.

(not required if you dont intend to run a store from the server)

Apache HTTP Server can be obtained here.

PHP can be obtained here.

After this install MySQL, it can be obtained here.

Next install Apache Tomcat

Apache Tomcat can be obtained here.

The Tomcat setup will look for the JRE, and should find the install path automatically.

(If not, then specify where you installed the JRE)

The default port will be set to 8080, seeing as Apache HTTP is already running on port 80.

Tomcat will prompt for an admin password, enter one and remember what it is.

The default installation does not ask you about memory allocations.

Bring up the Tomcat configuration tool after it is installed.

Navigate to the Java tab and set the initial memory size to 256 and the maximum memory

size to 1600 (the max allowed on 32bit Windows systems) or the maximum RAM capacity

on your server.

This is enough to package most any size ebook.

Important

Something omitted from the original documentation is that Tomcat will require Connector/J

to succesfully link to MySQL via the JDBC driver to Tomcat.

The MySQL JDBC driver can be obtained here.

(Read the included documentation on setting up Connector/J using Tomcat)

Once unpacked, the included .jar file needs to be placed into the Tomcat install path under

the \lib\ directory. Restart Tomcat to ensure the new .jar is loaded up.

The next installation is OpenSSL which appears much later in the adobe documentation,

and we will avoid some confusion by setting it up now, before we continue with

configuration later.

The easiest way to obtain OpenSSL for Windows is through Cygwin (a UNIX emulator).

Get Cygwin here.

Run setup.exe and when prompted select Install from Internet.

Follow all the setup steps, select a mirror to download a list of available Cygwin library files,

and soon you should be presented with a tree view of different packages.

Expand the Libs section of the tree, find the OpenSSL packages, and left click the arrows in

the columns until the text changes from skip to a version number next to each.

Proceed with the installation, and it will download OpenSSL.

Once the download is done, exit the installer.

To run Cygwin commands from the Windows command line, instead of the Cygwin shell,

include the full path to the Cygwin \bin\ folder into the windows PATH variable.

If you are having trouble installing OpenSSL some detailed instructions on installing

OpenSSL can be found here.

The basic requirements are now set up.

==

Adobe Content Server 4 (ACS4) Setup Guide - Part 2

Next we can proceed with setting up Adobe Content Server itself.

Setting up the database (if you have an existing database you may skip this step)

I will not be covering how to create databases within MySQL.

Either using the command line, MySQL Administrator or an interface tool such

asphpMyAdmin

create a new database named Adept. (SQL: CREATE DATABASE adept;)

Once done, you need to create a user and assign the right privileges.

The easiest way to do this is to use the MySQL Administrator client.

You need to create a user. Then you need to assign all SQL operators to that user.

Set the permitted operations per hour. 

Suggested setting is quite high (e.g. 10,000 operations per hour)

Lastly be sure to remember the user password.

Next we will set up the ACS4 folder locations and files.

Extract the ACS4 zip file to a simple location eg. C:\ACS4

You should see the following set of files (excluding the documentation):

ACS3toACS4convert_4_0_18.zip

admin-conf.txt

admin.war

fulfillment.war

fulfilment-conf.txt

operatorClient.jar

packaging-conf.txt

packaging.war

sample_books.zip

sample_store-20080908.zip

UploadTest-1_1.jar

UploadTest-1_1.zip

We start by copying the three .war files to the default web directory of Tomcat

(C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps)

admin.war

fulfillment.war

packaging.war

Setting up signed URL certificates

With OpenSSL installed, you need to create some URL certificate files.

Here are the steps with some elaboration:

The License Signing service (hosted by Adobe) needs a certificate signing request in format.

The following command line uses OpenSSL to create an PKCS10 RSA Keypair and

a CSR in PKCS10 format:

openssl req -newkey rsa:1024 -out operator.pkcs10 -keyout operator.key

You then need to answer questions on the command line

It doesn't really matter what you enter as those values will be overwritten in the certificate

creation process on the License Signing server.

You will also be prompted to enter a password (and then confirm it).

Be sure to remember this password!

You should see something similar to this appear as you answer one line at a time:

Country Name (2 letter code) [AU]: US

State or Province Name (full name) [Some-State]: California

Locality Name (eg, city) []: San Jose

Organization Name (eg, company) [Internet Widgets Pty Ltd]: Adobe

Organizational Unit Name (eg, section) []: Digital Publishing

Common Name (eg, YOUR name) []: Ric Wright

Email Address []: contentserver_support@adobe.com

You will then see the following prompt and two more questions.

DONT answer them. They are not needed, and in some cases can cause a crash.

Please enter the following 'extra' attributes to be sent with your certificate request.

A challenge password []:

An optional company name []:

Once done, exit the command line.

The result of this is the file operator.pkcs10, which will contain the certificate request (to

be uploaded to Adobe) and the file operator.key, which will contain the password-

protected private key.

Next, you need to upload those files to Adobe using the operatorClient.

In C:\ACS4\ is the zipped file containing operatorClient.jar.

Extract it from the zip file.

You can start the operatorClient by double-clicking.

You can also open a DOS prompt window, navigate to that folder and enter:

java -Xmx1024M –jar operatorClient.jar

if this returns an error, try a lower Ram setting such as:

java -Xmx512M –jar operatorClient.jar

The authentication URL should be http://adeactivate.adobe.com/adept.

This is the default, but verify that it is correct.

The License Signing URL should be https://nasigningservice.adobe.com/licenseadmin if you

are fulfilling books from North America.

Otherwise, you should change it to https://eusigningservice.adobe.com/licenseadmin

Note that in either case the URL must be https.

Login using the Adobe ID sent to you by Adobe.

It will be of the form acs4operator@yourdomain.com.

The password will be some variant of ChangeMe.

You can and should change that password by navigating to here

Now you need to add the fulfillment URL for your server.

Go to the Operator URLs tab.

Enter the URL that you will be using for your fulfillment server.

If the port you are using is 80 for HTTP (or 443 for HTTPS), you may omit the port.

But if you are using a different port, the value of the port must be specified as well,

e.g. http://mydomain.com:8080/

The URL must include the full path to the fulfillment service

e.g. http://mydomain.com:8080/fulfillment and not http://mydomain.com/

Once you have entered the correct fulfillment URL, press the Choose button and navigate

to the pkscs10 file you created using OpenSSL.

The Result File will be automatically entered for you.

When you are sure it is correct, press Add.

This will make a call to the Adobe servers, which will create and download

theoperator.cer file. This will take a few seconds.

The LicenseSigning service returns the certificate in DER format.

OpenSSL p12 packaging requires the certificate to be in PEM format.

To convert from DER to PEM use the following OpenSSL command line:

openssl x509 -in operator.cer -inform DER -out operator.pem -outform PEM

Assuming you named the output file operator.pem, run this command to package the

certificate and the key together next:

openssl pkcs12 -export -in operator.pem -inkey operator.key -name operator –out

operator.p12

The result of this should be the file operator.p12

Verify that it is in the folder.

It is important to note that the parameter –name operator specifies, as implied, the name

of the operator (being the operator of ACS4).

So when you set up your fulfillment configuration you will need to specify the location of

the operator.p12 file, the name of the operator of that file and the password.

So the name can be any one you like. 

In the above example the name is operator, but it could also be

acs4operator@domain.com 

So long as it matches your fulfillment.conf file all will be well.

Which brings us to our next step in the setup process.

==

Adobe Content Server 4 (ACS4) Setup Guide - Part 3

Setting Up the Configuration Files

By default, these files are named:

admin-conf.txt

fulfillment-conf.txt

packaging-conf.txt

And they are located, by default in: C:\config\ on Windows and /etc on Linux. 

Create the folder C:\config\ and put the configuration files there.

None of the config files have any values filled in. Add in the proper values next. 

First, set up the admin console configuration since it is the simplest and the others are

essentially extensions of it.

Admin Console Configuration

The first two lines are about what to log and where to put that information.

The next three lines specify the type of database and the driver to be used and the path

through which Content Server can find it.

The next two lines are the ID and password of the user you created when you created the

database.

The last line in the file is the URL to where the admin WAR can be found, complete with the

port (if it is not port 80). 

When entering the serviceURL there should be no spaces before or after the URL.

And that's it, after completion it should look something like this:

com.adobe.adept.log.level=trace

com.adobe.adept.log.file=C:\acs4\log\fulfillment.log

com.adobe.adept.persist.sql.driverClass=com.mysql.jdbc.Driver

com.adobe.adept.persist.sql.dialect=mysql

com.adobe.adept.persist.sql.connection=jdbc:mysql://127.0.0.1:3306/adept

com.adobe.adept.persist.sql.user=dbusername

com.adobe.adept.persist.sql.password=dbpassword

com.adobe.adept.serviceURL=http://yourdomain.com:8080/admin

You must always restart the Tomcat service after modifying the configuration files(since

they are only read during the Tomcat startup), so restart Tomcat now.

You can test that the admin.war is properly configured.

Go to a browser and enter the service URL plus /statuscheck,

e.g. http://yourdomain.com:8080/admin/statuscheck

You should get all green marks, if you get errors then try the following verbose report

method:

http://yourdomain.com:8080/admin/Status?verbose=true

This will give you more detailed information.

The most common problem of configuration is simply mistyping an address or value.

Also check for trailing spaces or spaces around the equals sign for properties.

Double check all the values.

Starting the Admin Console

As a final test that you have the configuration for the Admin Console correct, start it up.

To launch the admin console, enter into your browser the path to the admin console,

e.g. http://yourdomain.com:8080/admin/console 

Note: The client machine must have Flash Player 9 (or higher) installed to run the Admin

Console application.

The Admin Console will prompt you for a password.

The default password is park345 and once you have entered that it will then prompt you to

enter a new password. Note that this password is the one for the built-in distributor, as

opposed to distributors that you will create.

You can think of this as the Content Server password, but it will normally be referred to as

the password for the built-in distributor.

Once you have done that you will see the Admin Console.

The Admin Console isn't too interesting right now because you haven't packaged any books

yet.

Fulfillment Configuration

Now set up the fulfillment configuration. The config file is basically the same information as

that in the admin config file plus the properties specific to fulfillment.

The first line that differs is the URL to the actual fulfillment server:

com.adobe.adept.serviceURL=http://yourdomain.com:8080/fulfillment

This URL must include the port info if it is not port 80. 

In this case, Tomcat is on port 8080 so we need to include this. 

This URL must match exactly that which was specified when the certificate was created.

Do not use spaces before or after the equal sign, as this will cause a problem when

determining if the URLs match.

The first new property specifies which of the two license-signing services Content Server

will call to get licenses signed.

If you are in Canada or the US, you should specify: 

com.adobe.adept.fulfillment.security.licensesignURL=

https://nasigningservice.adobe.com/licensesign 

Otherwise, specify

com.adobe.adept.fulfillment.security.licensesignURL=

https://eusigningservice.adobe.com/licensesign

The last 3 lines are the location of the PKCS12 file, the certificate ID, and certificate

password.

com.adobe.adept.fulfillment.security.pkcs12.file=file:///C:/ACS4/operator.p12

com.adobe.adept.fulfillment.security.keystore.user=operator

com.adobe.adept.fulfillment.security.keystore.password=password

So the final fulfillment config contents are: 

com.adobe.adept.log.level=trace

com.adobe.adept.log.file=C:\ACS4\log\fulfillment.log

com.adobe.adept.persist.sql.driverClass=com.mysql.jdbc.Driver

com.adobe.adept.persist.sql.connection=jdbc:mysql://127.0.0.1:3306/adept

com.adobe.adept.persist.sql.dialect=mysql com.adobe.adept.persist.sql.user=dbuser

com.adobe.adept.persist.sql.password=dbpassword

com.adobe.adept.serviceURL=http://yourdomain.com:8080/fulfillment

com.adobe.adept.fulfillment.security.licensesignURL=https://

nasigningservice.adobe.com/licensesign

com.adobe.adept.fulfillment.security.pkcs12.file=file:///C:/ACS4/operator.p12

com.adobe.adept.fulfillment.security.keystore.user=operator

com.adobe.adept.fulfillment.security.keystore.password=password

Again, the URL to the fulfillment status would be:

http://yourdomain.com:8080/fulfillment/statuscheck/ 

Or append Status?verbose=true in place of statuscheck for more info

Packaging Configuration

The packaging configuration, like the fulfillment configuration file, is the same as the admin

console configuration file with the addition of the packaging-specific properties.

The service URL is of course pointing to the packaging .war file:

com.adobe.adept.serviceURL=http://yourdomain.com:8080/packaging 

The next two lines specify the destination of the packaged file and how it will be deployed

for download.

The baseLocation is where on the destination server's storage the book will be placed.

The baseURL determines at what apparent URL the book will be.

Note that the baseLocation has to be relative to the Tomcat instance. 

The default installation of Tomcat is: 

C:\Program Files\Apache Software Foundation\Tomcat 6.0

Tomcat addressing is relative to that location.

So if you want the baseLocation to be ebooks, then the baseLocation property has to be

relative to the ROOT folder of the Tomcat folder,

e.g .\webapps\ROOT\ 

So for example, if the baseLocation is .\webapps\ROOT\media and

the baseURL ishttp://yourdomain.com:8080/ebooks then when the book foo.epub is added it

will be at the path .\webapps\ROOT\media\foo.epub and will be available (via Tomcat

services)at http://yourdomain.com/ebooks/foo.epub. 

Of course, this is a function of how the Apache HTTP and Tomcat services are configured,

but the above is true for a normal set up.

So here are the resulting packaging-conf.txt contents:

com.adobe.adept.log.level=trace com.adobe.adept.log.file=C:\acs4\log\

packaging.log

com.adobe.adept.persist.sql.driverClass=com.mysql.jdbc.Driver

com.adobe.adept.persist.sql.connection=jdbc:mysql://127.0.0.1:3306/adept

com.adobe.adept.persist.sql.dialect=mysql

com.adobe.adept.persist.sql.user=dbuser

com.adobe.adept.persist.sql.password=dbpassword

com.adobe.adept.serviceURL=http://yourdomain.com/packaging

com.adobe.adept.packaging.baseLocation=.\webapps\ROOT\media

com.adobe.adept.packaging.baseURL=http://gort.corp.adobe.com:8080/media

Restart Tomcat one more time then check the status of the packaging service. 

The URL to the packaging status would be:

http://yourdomain.com:8080/packaging/statuscheck/ 

Or append Status?verbose=true in place of statuscheck for more info.

Now that Content Server is working, lets package some books.

==

Adobe Content Server 4 (ACS4) Setup Guide - Part 4

Packaging Books

The packaging tool is simple command line tool written in Java that makes the appropriate

calls to the packaging services web-service API's.

The tool is provided as source code (as well as the pre-built jar file).

The input to the tool is an unencrypted book and, optionally, some metadata.

The result is the encrypted book is written to the place specified by the packaging

configuration (the baseLocation) and the data about the book (its key, location, URL,

etc.) are written to the Content Server database.

Included in the release zip is a set of (public domain) books, book-cover images and XML

packaging files.

Unzip that file to some convenient location (e.g. C:\ACS4\srcbooks).

The packaging tool can be used to package individual books by themselves, but it is often

more convenient to use a helper file that constitutes a packaging request, but we'll start

out by packaging an individual file.

The inputs to the tool are the URL to the packaging service, the path to the book itself and

the password used to log into the ACS4 admin console.

So if one navigates to the folder the books and tha packaging tool are in, and enter:

java –Xmx1024M –jar UploadTest-1_1.jar

http://yourdomain.com:8080/packaging/Package srcbooks\MonteCristo.epub –

pass password

The parameter –Xmx1024M tells the Java Virtual Machine (JVM) to allocate 1 GB for the

process.

This isn't needed for small files, but large complex files may fail otherwise (and the JVM will

often emit bizarre, misleading messages when it runs out of memory). 

For very large files you may want to allocate even more memory.

Note that the tool needs to address the Package service inside the packaging WAR, hence

the packaging/Package in the URL.

Although the above works, parameters can also be passed in an XML file that contains the

packaging information.

So for example, the following command:

java –Xmx1024M –jar UploadTest-1_1.jar

http://yourdomain.com:8080/packaging/Package srcbooks\theArtofWar.pdf –pass

password -xml -jpg 

will cause the file theArtofWar.epub to be packaged and the file theArtofWar.jpg to be

placed in the same destination folder. It will also cause the tool to load the xml file from the

same folder and read the metadata and permissions from it.

The following command will package all the books in a given folder:

java –Xmx1024M –jar UploadTest-1_1.jar

http://yourdomain.com:8080/packaging/Package srcbooks –pass password -xml -

jpg

The Admin Console (continued)

So now that there are packaged books, bring up the Admin Console again. Remember that

the password is now the new one that you entered the first time you brought it up.

There are three panels in the Console:

Inventory,

Distributors,

and Licenses.

By default the Inventory panel is selected. The books that you just packaged should be

shown.

If they do not, click on the All Items icon and you should see all the items you have

packaged in the current database.

You can sort the items in the inventory by just clicking on the header of the column.

You can also search for specific book's text in the title, author etc.

To clear a search, click on the All Items icon again. Note that down at the bottom is an area

titled Web Services APIs. This is just informational and primarily for developer's interest.

It shows what is happening under the covers. When you make some gesture in the

Console (like clearing a search), the Console makes a web-service call to the Content

Server fulfillment service and gets back some XML that represents the results of the search.

This can be very useful information for developers investigating problems or as tutorials as

they learn how to develop their own tools or integrate Content Server with their own

systems.

On the right, you will see basic information about the book. 

Select one of the books and you will see its information displayed (title, author, etc.) as well

as the thumbnail of the book (assuming it was packaged with the thumbnail, i.e. –jpg was

specified).

Below the basic information is the permissions info. These are the parameters that control

what a user who downloads a book can do with it.

With Content Server you can control how many machines or devices a book can be

downloaded to, whether and how much the user can print from the book, whether the user

can copy to the clipboard and so on. (The User Manual and Technical Reference cover these

elements in some depth). 

There are two types of permissions: 

Base Permissions: 

These are the permissions you specified when the book was packaged (in the XML file, if

specified). These are part of the packaged book. You can edit them in the Admin Console,

essentially overriding the permissions that were specified when the book was packaged.

But note that this will change the base permissions associated with the packaged books

and will affect any and all distributions of the book. 

Distributor Permissions: 

With Content Server you can also narrow the permissions on a per-distributor basis. In other

words, you can make the permission more restrictive for any particular distributor or for all

distributors. But you cannot make the permissions less restrictive.

If you check the Distribution Rights for the selected book, you will find it tells you:

“No Distributor Selected” - naturally enough, since we haven't created one yet.

So what IS a distributor?

A Distributor is an entity such as a bookstore or library through which you, as the Content

Server operator, distributes books.

Again, there is the Built-in Distributor, but this should be thought of as the Master or root.

It is not a Distributor in the normal sense and should not be used to distribute books.

Navigate to the Distributor panel by clicking on the Distributors link at the top of the

console. This takes you to the Distributors panel. It is similar to the Inventory panel in that

it lists all the Distributors, which can be sorted, searched, the properties examined and so

on.

But at the moment there arent any, so click on the little + (plus) sign button on the bottom

right to create a new Distributor. This will bring up a dialog prompting you to enter some

properties for the new Distributor:

Name: Just the human readable label for the store

URL: The URL where the store will be located (more on this below)

Notify URL: The URL to which Content Server will instruct Digital Editions to send a

notification when a transaction is verified complete and the user has the valid eBook.

Digital Editions will also send a notification to this address when a loaned book is

returned. This is an optional field.

Description: A human readable description of the site

Max Loan Count: The maximum number of loans a distributor can make of any given

eBook. Many publishers restrict the number of copies of a given ebook that can be

loaned at any one time to 1. After all, a library can only loan out the single copy of a

real hardcover book at a time.

Link Expires: The length of time after which a generated link is no longer valid, in

seconds.

Shared Secret: This is an automatically generated number which is known only to the

Distributor and Content Server. Using this number, messages between the two can

be digitally signed in such a way that each knows that only the other party could

have sent the message.

Save the info. Now, you will see that you have distributor listed.

If you select it, then the properties are now editable on the right hand side. And the only

books shown in the inventory will be those that have been assigned to that Distributor.

You're almost ready to enable a Distributor using the supplied Content Server sample store.

But you need to actually assign some books to the distributor.

So go back to the Inventory panel. The new Distributor now appears on the left side. You

can simply drag books from the inventory pane over and drop them on the Distributor.

Do that for some books then you're ready to install the Store.

If you made it to this point and opt not to install the sample store, congratulations, as you

now have a working version of Adobe Content Server installed either way.

To complete this tutorial and set up the sample store, and deliver some ebooks, click here.

==

Adobe Content Server 4 (ACS4) Setup Guide - Part 5

The Sample Store

The sample store is contained in a zip file that came with the rest of Content Server.

To operate the sample store you need a web server that can actually serve up the

store (i.e. respond to HTTP requests and fetch the necessary resources from the PHP that

comprises the store.) 

Assuming you installed Apache as outlined at the beginning of the guide, all you need to do

is extract the contents of the zip file to a folder here:

C:\Program Files\Apache Software Foundation\Apache2.2\htdocs 

For simplicity, extract the contents into a new folder in htdocs called bookstore.

Then your new bookstore will be addressed like this:

http://yourdomain.com/bookstore 

The store is installed. Now let's set it up. 

Go back to the Admin Console and open the Distributor's panel.

Click on the Export Sample Site button. You will see a dialog (without the URL filled in).

You need to perform two operations: 

1. Export the Catalog XML file (books.xml). This is what it suggests, an XML file that

contains all books that are assigned to the specified distributor.

2. Store the Config XML file (config.xml). This is sets up the configuration file for the

store.

Select the radio-button next to the Catalog XML label and press Next. This will display

aSaveAs file dialog prompting you to select a location where the catalog.xml file should be

saved.

You must save the file into the same folder where you unpacked the Store files (in

htdocs/bookstore). Then select the radio-button next to Store Config.

Where it says “Enter link URL”, enter the exact link to the fulfillment service for Content

Server.

The store will construct the necessary link for fulfillment for this info, so it must include the

port (if any). Then press Next and it will again prompt you to save the config.xml file. Save

it to the same folder (htdocs/bookstore). You will then be back at the same dialog. Just

dismiss it now by choosing Close.

You typically only have to set up the config.xml file once, unless you change the URL to the

fulfillment service.

But you need to update the catalog (books.xml) anytime you change any part of the

catalog – books, permissions, etc.

Now, go back to your browser and enter the URL to the bookstore,

e.g. http://yourdomain.com/bookstore/index.htm

You should see a page that contains the books that were exported to that Distributor.

Click on purchase and you will be taken to another page with more choice to further restrict

the permissions on the book. This is not part of a normal store, of course, but this is a

sample test app.

Click on the purchase button again and it will take you to the “Thank you” page.

This is the page normally presented by a web site after the user has presented their money

and/or accreditation.

Click on “Download” and the download to Adobe Digital Editions should start.

And that's it. You now have a complete, end to end installation of Content Server.

As a last note, you can check out transaction logs using the operatorClient tool, should you

want to.

Thank you for reading this tutorial and i hope it was of some help.