Skip to content
Snippets Groups Projects
Commit 4dc2728a authored by Andreas Åkre Solberg's avatar Andreas Åkre Solberg
Browse files

Adding docmentation on alternative installation paths 

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@921 44740490-163a-0410-bde0-09ae8108e29a
parent a93c356e
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/source/simplesamlphp-install.xml
+ 173
− 73
View file @ 4dc2728a
......@@ -7,7 +7,7 @@
<articleinfo>
<date>2007-08-30</date>
<pubdate>Thu Mar 27 20:47:10 2008</pubdate>
<pubdate>Thu Oct 16 09:35:10 2008</pubdate>
<author>
<firstname>Andreas Åkre</firstname>
......@@ -27,7 +27,8 @@
<itemizedlist>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all <application>simpleSAMLphp</application> documentation</ulink></para>
all <application>simpleSAMLphp</application>
documentation</ulink></para>
</listitem>
</itemizedlist>
</section>
......@@ -35,33 +36,37 @@
<section>
<title>News about simpleSAMLphp</title>
<para>To get the latest news about <application>simpleSAMLphp</application> you can follow this url:
<ulink
<para>To get the latest news about
<application>simpleSAMLphp</application> you can follow this url: <ulink
url="http://rnd.feide.no/taxonomy/term/4">http://rnd.feide.no/taxonomy/term/4</ulink>.
It also conatins an RSS feed.</para>
<para>Here is the <application>simpleSAMLphp</application> homepage: <ulink
<para>Here is the <application>simpleSAMLphp</application> homepage:
<ulink
url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
</section>
<section>
<title>Prerequisites</title>
<para><application>PHP</application> version &gt;= 5.1.2. If you want to run the
<emphasis>Shibboleth 1.3</emphasis> part
of <application>simpleSAMLphp</application>, you must have <application>PHP</application> &gt;= 5.2.</para>
<para><application>PHP</application> version &gt;= 5.1.2. If you want to
run the <emphasis>Shibboleth 1.3</emphasis> part of
<application>simpleSAMLphp</application>, you must have
<application>PHP</application> &gt;= 5.2.</para>
<para>Apache or some other webserver.</para>
<para><application>simpleSAMLphp</application> is has been tested most thoroughly on different Linux
versions, Unix, and Mac OS X. It also runs on Windows, but at the time of
writing, testing has been less thorough.</para>
<para><application>simpleSAMLphp</application> is has been tested most
thoroughly on different Linux versions, Unix, and Mac OS X. It also runs
on Windows, but at the time of writing, testing has been less
thorough.</para>
</section>
<section>
<title>Download and install simpleSAMLphp</title>
<para>The most recent relase of <application>simpleSAMLphp</application> is found at <ulink
<para>The most recent relase of <application>simpleSAMLphp</application>
is found at <ulink
url="http://code.google.com/p/simplesamlphp/">code.google.com/p/simplesamlphp/.</ulink>
To obtain a stable version, you may download the zipped
<filename>simplesamlphp</filename> zip file listed under Featured
......@@ -89,13 +94,14 @@ svn up</screen>
</section>
<section id="sect.upgrading">
<title>Upgrading from a previous version of <application>simpleSAMLphp</application></title>
<title>Upgrading from a previous version of
<application>simpleSAMLphp</application></title>
<para><emphasis>If you have downloaded a version from the subversion
repository:</emphasis></para>
<para>Type, while located in the root folder of your <application>simpleSAMLphp</application>
installation:</para>
<para>Type, while located in the root folder of your
<application>simpleSAMLphp</application> installation:</para>
<screen>svn update</screen>
......@@ -125,9 +131,9 @@ svn up</screen>
</itemizedlist></para>
<para>If the format of the config files or metadata has changed from your
previous version of <application>simpleSAMLphp</application> (check the revision log), you may have
to update your configuration and metadata after updating the <application>simpleSAMLphp</application>
code:</para>
previous version of <application>simpleSAMLphp</application> (check the
revision log), you may have to update your configuration and metadata
after updating the <application>simpleSAMLphp</application> code:</para>
<section>
<title>Upgrading config.php</title>
......@@ -157,8 +163,8 @@ svn up</screen>
<tip>
<para>You do not need to read this section if you are upgrading
<application>simpleSAMLphp</application> from an earlier version, then see <xref
linkend="sect.upgrading" />.</para>
<application>simpleSAMLphp</application> from an earlier version, then
see <xref linkend="sect.upgrading" />.</para>
</tip>
<para>Configuration and metadata files are distributed as templates; you
......@@ -177,22 +183,24 @@ cp -r metadata-templates/*.php metadata/
</screen>
</section>
<section>
<section id="sect.apacheconfig">
<title>Configuring Apache</title>
<para>Examples below assume that <application>simpleSAMLphp</application> is installed in the default
location, <filename>/var/simplesamlphp</filename>. You may choose another
location, but this requires a path update in a few files. <link
<para>Examples below assume that <application>simpleSAMLphp</application>
is installed in the default location,
<filename>/var/simplesamlphp</filename>. You may choose another location,
but this requires a path update in a few files. <link
linkend="sect.altlocations">See Appendix A for details</link>.</para>
<para>The only subdirectories of <filename>simpleSAMLphp</filename> that
needs to be accessible from the web is <filename>www</filename>. There are
several ways of putting the <application>simpleSAMLphp</application> depending on the way web sites
are structured on your apache web server. Here is what I believe is the
best configuration.</para>
several ways of putting the <application>simpleSAMLphp</application>
depending on the way web sites are structured on your apache web server.
Here is what I believe is the best configuration.</para>
<para>Find the Apache configuration file for the virtual hosts where you
want to run <application>simpleSAMLphp</application>. The configuration may look like this:</para>
want to run <application>simpleSAMLphp</application>. The configuration
may look like this:</para>
<programlisting>&lt;VirtualHost *&gt;
ServerName service.example.com
......@@ -205,13 +213,14 @@ cp -r metadata-templates/*.php metadata/
<para>Note the <literal>Alias</literal> directive, which gives control to
<application>simpleSAMLphp</application> for all urls matching
<literal>http(s)://service.example.com/simplesaml/*</literal>.
<application>simpleSAMLphp</application> makes several SAML interfaces available on the web; all of
them are included in the <filename>www</filename> subdirectory of your
<application>simpleSAMLphp</application> installation. You can name the alias whatever you want, but
the name must be specified in the <filename>config.php</filename> file of
simpleSAML as described in <xref linkend="sect.config" />. Here is an
example of how this configuration may look like in
<filename>config.php</filename>:h</para>
<application>simpleSAMLphp</application> makes several SAML interfaces
available on the web; all of them are included in the
<filename>www</filename> subdirectory of your
<application>simpleSAMLphp</application> installation. You can name the
alias whatever you want, but the name must be specified in the
<filename>config.php</filename> file of simpleSAML as described in <xref
linkend="sect.config" />. Here is an example of how this configuration may
look like in <filename>config.php</filename>:h</para>
<programlisting>$config = array (
[...]
......@@ -227,9 +236,10 @@ cp -r metadata-templates/*.php metadata/
<section>
<title>The simpleSAMLphp installation webpage</title>
<para>After installing <application>simpleSAMLphp</application>, you can access the homepage of your
installation, which contains some information and a few links to the test
services. The url of an installation can be e.g.:</para>
<para>After installing <application>simpleSAMLphp</application>, you can
access the homepage of your installation, which contains some information
and a few links to the test services. The url of an installation can be
e.g.:</para>
<literallayout>https://service.example.com/simplesaml/</literallayout>
......@@ -238,12 +248,12 @@ cp -r metadata-templates/*.php metadata/
<warning>
<para>Don't click on any of the links yet, because they require you to
either have setup <application>simpleSAMLphp</application> as an Service Provider or as an Identity
Provider.</para>
either have setup <application>simpleSAMLphp</application> as an Service
Provider or as an Identity Provider.</para>
</warning>
<para>Here is an example screenshot of what the <application>simpleSAMLphp</application> page looks
like:</para>
<para>Here is an example screenshot of what the
<application>simpleSAMLphp</application> page looks like:</para>
<figure>
<title>Screenshot of the simpleSAMLphp installation page.</title>
......@@ -263,19 +273,21 @@ cp -r metadata-templates/*.php metadata/
<para>At the bottom of the installation page are some green lights.
simpleSAML runs some tests to see whether required and recommended
prerequisites are met. If any of the lights are red, you may have to add
some extensions or modules to <application>PHP</application>, e.g. you need the PHP LDAP extension
to use the LDAP authentication module.</para>
some extensions or modules to <application>PHP</application>, e.g. you
need the PHP LDAP extension to use the LDAP authentication
module.</para>
</section>
</section>
<section>
<title>Next steps</title>
<para>You have now successfully installed <application>simpleSAMLphp</application>, and the next
steps depends on whether you want to setup a service provider, to protect
a website by authentication or if you want to setup an identity provider
and connect it to a user catalog. Documentation on bridging between
federation protocols is found in a separate document.</para>
<para>You have now successfully installed
<application>simpleSAMLphp</application>, and the next steps depends on
whether you want to setup a service provider, to protect a website by
authentication or if you want to setup an identity provider and connect it
to a user catalog. Documentation on bridging between federation protocols
is found in a separate document.</para>
<itemizedlist>
<listitem>
......@@ -313,33 +325,38 @@ cp -r metadata-templates/*.php metadata/
<section>
<title>Support</title>
<para>If you need help to make this work, or want to discuss <application>simpleSAMLphp</application>
with other users of the software, you are fortunate: Around <application>simpleSAMLphp</application>
there is a great Open source community, and you are welcome to join! The
forums are open for you to ask questions, contribute answers other further
<para>If you need help to make this work, or want to discuss
<application>simpleSAMLphp</application> with other users of the software,
you are fortunate: Around <application>simpleSAMLphp</application> there
is a great Open source community, and you are welcome to join! The forums
are open for you to ask questions, contribute answers other further
questions, request improvements or contribute with code or plugins of your
own.</para>
<itemizedlist>
<listitem>
<para><ulink url="http://rnd.feide.no/simplesamlphp"><application>simpleSAMLphp</application>
<para><ulink
url="http://rnd.feide.no/simplesamlphp"><application>simpleSAMLphp</application>
homepage (at Feide RnD)</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all available <application>simpleSAMLphp</application> documentation</ulink></para>
all available <application>simpleSAMLphp</application>
documentation</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
the <application>simpleSAMLphp</application> user's mailing list</ulink></para>
the <application>simpleSAMLphp</application> user's mailing
list</ulink></para>
</listitem>
<listitem>
<para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
contribute to the <application>simpleSAMLphp</application> wiki</ulink></para>
contribute to the <application>simpleSAMLphp</application>
wiki</ulink></para>
</listitem>
</itemizedlist>
</section>
......@@ -347,25 +364,60 @@ cp -r metadata-templates/*.php metadata/
<appendix id="sect.altlocations">
<title>Installing simpleSAMLphp in alternative locations</title>
<para>You can separate the <literal>www</literal> subdirectory of
<filename>simpleSAMLphp</filename> from the installation directory. You
need to set the path of the installation directory in the
<filename>config.php</filename> file:</para>
<para>There may be several reasons why you want to install simpleSAMLphp
in an alternative way. </para>
<orderedlist>
<listitem>
<para>You are installing simpleSAMLphp in a hosted environment where
you do not have root access, and cannot change Apache configuration.
Still you can install simpleSAMLphp - keep on reading.</para>
</listitem>
<listitem>
<para>You have full permissions to the server, but cannot edit Apache
configuration for some reason, polictics, policy or whatever.</para>
</listitem>
</orderedlist>
<para>The SimpleSAMLphp code contains one folder named
<filename>simplesamlphp</filename>. In this folder there are a lot of
subfolders for library, metadata, configuration and much more. One of
these folders is named <filename>www</filename>. This and <emphasis>only
this</emphasis> folder should be exposed on the web. The reccomended
configuration is to put the whole <filename>simplesamlphp</filename>
folder outside the webroot, and then link in the <filename>www</filename>
folder by using the <literal>Alias</literal> directive, as described in
<xref linkend="sect.apacheconfig" />. But this is not the only possible
way.</para>
<para>As an example, let's see how you can install simpleSAMLphp in your
home directory on a shosted server.</para>
<para>Check out simpleSAMLphp in your home directory, and move or symlink
the www folder into the <filename>public_html</filename> folder.</para>
<screen>cd ~
svn checkout [snipp] simplesamlphp
</screen>
<programlisting> 'basedir' =&gt; '/usr/local/simplesaml/simplesamlphp',</programlisting>
<para>Then you can try to make a symlink into the public_html
directory.</para>
<para>And you also need to modify the <literal>Alias</literal> directive
in the apache configuration:</para>
<screen>cd ~/public_html
ln -s ../simplesamlphp/www simplesaml
</screen>
<programlisting> Alias /simplesaml /usr/local/simplesaml/simplesamlphp/www</programlisting>
<tip>
<para>Symlinking may fail, because some apache configurations do not
allow you to link in files from outside the public_html folder. If so,
move the folder instead of symlinking:</para>
<para>You also need to change the path of the <literal>require_once(...
_include.php)</literal> line in the examples and in your integration
code.</para>
<screen>cd ~/public_html
mv ../simplesamlphp/www simplesaml</screen>
</tip>
<para>One case where you might want to make this separation is if you must
install <application>simpleSAMLphp</application> in your home directory, and you would like the
following directory structure:</para>
<para>Now you have the following directory structure.</para>
<itemizedlist>
<listitem>
......@@ -373,10 +425,58 @@ cp -r metadata-templates/*.php metadata/
</listitem>
<listitem>
<para><filename>~/publichtml/simplesaml</filename> where simplesaml is
the <filename>www</filename> directory from the <filename>simplesamlphp</filename> installation
<para><filename>~/public_html/simplesaml</filename> where
<filename>simplesaml</filename> is the <filename>www</filename>
directory from the <filename>simplesamlphp</filename> installation
directory, either moved or a symlink.</para>
</listitem>
</itemizedlist>
<para>Now, we need to make a few configuration changes. First, let's edit
<filename>~/public_html/simplesaml/_include.php</filename>:</para>
<para>Change the two lines from:</para>
<programlisting>require_once(dirname(dirname(__FILE__)) . '/lib/_autoload.php');
$path_extra = dirname(dirname(__FILE__)) . '/lib';</programlisting>
<para>to something like:</para>
<programlisting>require_once('/home/andreas/simplesamlphp/lib/_autoload.php');
$path_extra = '/home/andreas/simplesamlphp/lib';</programlisting>
<para>And then at the end of the file, you need to change another line
from:</para>
<programlisting>$configdir = dirname(dirname(__FILE__)) . '/config';</programlisting>
<para>to:</para>
<programlisting>$configdir = '/home/andreas/simplesamlphp/config';</programlisting>
<note>
<para>In a future version of simpleSAMLphp we'll make this a bit easier,
and let you only change the path one place, instead of three as
described above.</para>
</note>
<para>Next, you need to update the configuration of paths in
<filename>simplesamlphp/config/config.php</filename>:</para>
<para>Set the <literal>basedir</literal> parameter to the path of your
simplesamlphp folder:</para>
<programlisting> 'basedir' =&gt; '/home/andreas/simplesamlphp/',</programlisting>
<para>And, then we need to set the <literal>baseurlpath</literal>
parameter to match the base path of the URLs to the content of your
<filename>www</filename> folder:</para>
<programlisting> 'baseurlpath' =&gt; '~andreas/simplesaml/',</programlisting>
<para>Now, you can go to the URL of your installation and check if things
work:</para>
<literallayout>http://yourcompany.com/~andreas/simplesaml/</literallayout>
</appendix>
</article>
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment