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 @@ ...@@ -7,7 +7,7 @@
<articleinfo> <articleinfo>
<date>2007-08-30</date> <date>2007-08-30</date>
<pubdate>Thu Mar 27 20:47:10 2008</pubdate> <pubdate>Thu Oct 16 09:35:10 2008</pubdate>
<author> <author>
<firstname>Andreas Åkre</firstname> <firstname>Andreas Åkre</firstname>
...@@ -27,7 +27,8 @@ ...@@ -27,7 +27,8 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of <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> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
...@@ -35,33 +36,37 @@ ...@@ -35,33 +36,37 @@
<section> <section>
<title>News about simpleSAMLphp</title> <title>News about simpleSAMLphp</title>
<para>To get the latest news about <application>simpleSAMLphp</application> you can follow this url: <para>To get the latest news about
<ulink <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>. url="http://rnd.feide.no/taxonomy/term/4">http://rnd.feide.no/taxonomy/term/4</ulink>.
It also conatins an RSS feed.</para> 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> url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
</section> </section>
<section> <section>
<title>Prerequisites</title> <title>Prerequisites</title>
<para><application>PHP</application> version &gt;= 5.1.2. If you want to run the <para><application>PHP</application> version &gt;= 5.1.2. If you want to
<emphasis>Shibboleth 1.3</emphasis> part run the <emphasis>Shibboleth 1.3</emphasis> part of
of <application>simpleSAMLphp</application>, you must have <application>PHP</application> &gt;= 5.2.</para> <application>simpleSAMLphp</application>, you must have
<application>PHP</application> &gt;= 5.2.</para>
<para>Apache or some other webserver.</para> <para>Apache or some other webserver.</para>
<para><application>simpleSAMLphp</application> is has been tested most thoroughly on different Linux <para><application>simpleSAMLphp</application> is has been tested most
versions, Unix, and Mac OS X. It also runs on Windows, but at the time of thoroughly on different Linux versions, Unix, and Mac OS X. It also runs
writing, testing has been less thorough.</para> on Windows, but at the time of writing, testing has been less
thorough.</para>
</section> </section>
<section> <section>
<title>Download and install simpleSAMLphp</title> <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> url="http://code.google.com/p/simplesamlphp/">code.google.com/p/simplesamlphp/.</ulink>
To obtain a stable version, you may download the zipped To obtain a stable version, you may download the zipped
<filename>simplesamlphp</filename> zip file listed under Featured <filename>simplesamlphp</filename> zip file listed under Featured
...@@ -89,13 +94,14 @@ svn up</screen> ...@@ -89,13 +94,14 @@ svn up</screen>
</section> </section>
<section id="sect.upgrading"> <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 <para><emphasis>If you have downloaded a version from the subversion
repository:</emphasis></para> repository:</emphasis></para>
<para>Type, while located in the root folder of your <application>simpleSAMLphp</application> <para>Type, while located in the root folder of your
installation:</para> <application>simpleSAMLphp</application> installation:</para>
<screen>svn update</screen> <screen>svn update</screen>
...@@ -125,9 +131,9 @@ svn up</screen> ...@@ -125,9 +131,9 @@ svn up</screen>
</itemizedlist></para> </itemizedlist></para>
<para>If the format of the config files or metadata has changed from your <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 previous version of <application>simpleSAMLphp</application> (check the
to update your configuration and metadata after updating the <application>simpleSAMLphp</application> revision log), you may have to update your configuration and metadata
code:</para> after updating the <application>simpleSAMLphp</application> code:</para>
<section> <section>
<title>Upgrading config.php</title> <title>Upgrading config.php</title>
...@@ -157,8 +163,8 @@ svn up</screen> ...@@ -157,8 +163,8 @@ svn up</screen>
<tip> <tip>
<para>You do not need to read this section if you are upgrading <para>You do not need to read this section if you are upgrading
<application>simpleSAMLphp</application> from an earlier version, then see <xref <application>simpleSAMLphp</application> from an earlier version, then
linkend="sect.upgrading" />.</para> see <xref linkend="sect.upgrading" />.</para>
</tip> </tip>
<para>Configuration and metadata files are distributed as templates; you <para>Configuration and metadata files are distributed as templates; you
...@@ -177,22 +183,24 @@ cp -r metadata-templates/*.php metadata/ ...@@ -177,22 +183,24 @@ cp -r metadata-templates/*.php metadata/
</screen> </screen>
</section> </section>
<section> <section id="sect.apacheconfig">
<title>Configuring Apache</title> <title>Configuring Apache</title>
<para>Examples below assume that <application>simpleSAMLphp</application> is installed in the default <para>Examples below assume that <application>simpleSAMLphp</application>
location, <filename>/var/simplesamlphp</filename>. You may choose another is installed in the default location,
location, but this requires a path update in a few files. <link <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> linkend="sect.altlocations">See Appendix A for details</link>.</para>
<para>The only subdirectories of <filename>simpleSAMLphp</filename> that <para>The only subdirectories of <filename>simpleSAMLphp</filename> that
needs to be accessible from the web is <filename>www</filename>. There are 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 several ways of putting the <application>simpleSAMLphp</application>
are structured on your apache web server. Here is what I believe is the depending on the way web sites are structured on your apache web server.
best configuration.</para> Here is what I believe is the best configuration.</para>
<para>Find the Apache configuration file for the virtual hosts where you <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; <programlisting>&lt;VirtualHost *&gt;
ServerName service.example.com ServerName service.example.com
...@@ -205,13 +213,14 @@ cp -r metadata-templates/*.php metadata/ ...@@ -205,13 +213,14 @@ cp -r metadata-templates/*.php metadata/
<para>Note the <literal>Alias</literal> directive, which gives control to <para>Note the <literal>Alias</literal> directive, which gives control to
<application>simpleSAMLphp</application> for all urls matching <application>simpleSAMLphp</application> for all urls matching
<literal>http(s)://service.example.com/simplesaml/*</literal>. <literal>http(s)://service.example.com/simplesaml/*</literal>.
<application>simpleSAMLphp</application> makes several SAML interfaces available on the web; all of <application>simpleSAMLphp</application> makes several SAML interfaces
them are included in the <filename>www</filename> subdirectory of your available on the web; all of them are included in the
<application>simpleSAMLphp</application> installation. You can name the alias whatever you want, but <filename>www</filename> subdirectory of your
the name must be specified in the <filename>config.php</filename> file of <application>simpleSAMLphp</application> installation. You can name the
simpleSAML as described in <xref linkend="sect.config" />. Here is an alias whatever you want, but the name must be specified in the
example of how this configuration may look like in <filename>config.php</filename> file of simpleSAML as described in <xref
<filename>config.php</filename>:h</para> linkend="sect.config" />. Here is an example of how this configuration may
look like in <filename>config.php</filename>:h</para>
<programlisting>$config = array ( <programlisting>$config = array (
[...] [...]
...@@ -227,9 +236,10 @@ cp -r metadata-templates/*.php metadata/ ...@@ -227,9 +236,10 @@ cp -r metadata-templates/*.php metadata/
<section> <section>
<title>The simpleSAMLphp installation webpage</title> <title>The simpleSAMLphp installation webpage</title>
<para>After installing <application>simpleSAMLphp</application>, you can access the homepage of your <para>After installing <application>simpleSAMLphp</application>, you can
installation, which contains some information and a few links to the test access the homepage of your installation, which contains some information
services. The url of an installation can be e.g.:</para> 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> <literallayout>https://service.example.com/simplesaml/</literallayout>
...@@ -238,12 +248,12 @@ cp -r metadata-templates/*.php metadata/ ...@@ -238,12 +248,12 @@ cp -r metadata-templates/*.php metadata/
<warning> <warning>
<para>Don't click on any of the links yet, because they require you to <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 either have setup <application>simpleSAMLphp</application> as an Service
Provider.</para> Provider or as an Identity Provider.</para>
</warning> </warning>
<para>Here is an example screenshot of what the <application>simpleSAMLphp</application> page looks <para>Here is an example screenshot of what the
like:</para> <application>simpleSAMLphp</application> page looks like:</para>
<figure> <figure>
<title>Screenshot of the simpleSAMLphp installation page.</title> <title>Screenshot of the simpleSAMLphp installation page.</title>
...@@ -263,19 +273,21 @@ cp -r metadata-templates/*.php metadata/ ...@@ -263,19 +273,21 @@ cp -r metadata-templates/*.php metadata/
<para>At the bottom of the installation page are some green lights. <para>At the bottom of the installation page are some green lights.
simpleSAML runs some tests to see whether required and recommended 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 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 some extensions or modules to <application>PHP</application>, e.g. you
to use the LDAP authentication module.</para> need the PHP LDAP extension to use the LDAP authentication
module.</para>
</section> </section>
</section> </section>
<section> <section>
<title>Next steps</title> <title>Next steps</title>
<para>You have now successfully installed <application>simpleSAMLphp</application>, and the next <para>You have now successfully installed
steps depends on whether you want to setup a service provider, to protect <application>simpleSAMLphp</application>, and the next steps depends on
a website by authentication or if you want to setup an identity provider whether you want to setup a service provider, to protect a website by
and connect it to a user catalog. Documentation on bridging between authentication or if you want to setup an identity provider and connect it
federation protocols is found in a separate document.</para> to a user catalog. Documentation on bridging between federation protocols
is found in a separate document.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
...@@ -313,33 +325,38 @@ cp -r metadata-templates/*.php metadata/ ...@@ -313,33 +325,38 @@ cp -r metadata-templates/*.php metadata/
<section> <section>
<title>Support</title> <title>Support</title>
<para>If you need help to make this work, or want to discuss <application>simpleSAMLphp</application> <para>If you need help to make this work, or want to discuss
with other users of the software, you are fortunate: Around <application>simpleSAMLphp</application> <application>simpleSAMLphp</application> with other users of the software,
there is a great Open source community, and you are welcome to join! The you are fortunate: Around <application>simpleSAMLphp</application> there
forums are open for you to ask questions, contribute answers other further 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 questions, request improvements or contribute with code or plugins of your
own.</para> own.</para>
<itemizedlist> <itemizedlist>
<listitem> <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> homepage (at Feide RnD)</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of <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>
<listitem> <listitem>
<para><ulink <para><ulink
url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join 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>
<listitem> <listitem>
<para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and <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> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
...@@ -347,25 +364,60 @@ cp -r metadata-templates/*.php metadata/ ...@@ -347,25 +364,60 @@ cp -r metadata-templates/*.php metadata/
<appendix id="sect.altlocations"> <appendix id="sect.altlocations">
<title>Installing simpleSAMLphp in alternative locations</title> <title>Installing simpleSAMLphp in alternative locations</title>
<para>You can separate the <literal>www</literal> subdirectory of <para>There may be several reasons why you want to install simpleSAMLphp
<filename>simpleSAMLphp</filename> from the installation directory. You in an alternative way. </para>
need to set the path of the installation directory in the
<filename>config.php</filename> file:</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 <screen>cd ~/public_html
in the apache configuration:</para> 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(... <screen>cd ~/public_html
_include.php)</literal> line in the examples and in your integration mv ../simplesamlphp/www simplesaml</screen>
code.</para> </tip>
<para>One case where you might want to make this separation is if you must <para>Now you have the following directory structure.</para>
install <application>simpleSAMLphp</application> in your home directory, and you would like the
following directory structure:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
...@@ -373,10 +425,58 @@ cp -r metadata-templates/*.php metadata/ ...@@ -373,10 +425,58 @@ cp -r metadata-templates/*.php metadata/
</listitem> </listitem>
<listitem> <listitem>
<para><filename>~/publichtml/simplesaml</filename> where simplesaml is <para><filename>~/public_html/simplesaml</filename> where
the <filename>www</filename> directory from the <filename>simplesamlphp</filename> installation <filename>simplesaml</filename> is the <filename>www</filename>
directory from the <filename>simplesamlphp</filename> installation
directory, either moved or a symlink.</para> directory, either moved or a symlink.</para>
</listitem> </listitem>
</itemizedlist> </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> </appendix>
</article> </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