From 9ec680be2a434c42ace1471fb6b230bf24c2d820 Mon Sep 17 00:00:00 2001
From: Olav Morken <olav.morken@uninett.no>
Date: Tue, 20 Oct 2009 12:12:09 +0000
Subject: [PATCH] docs: Separate out subversion installation instructions from
the main install guide.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1887 44740490-163a-0410-bde0-09ae8108e29a
---
docs/simplesamlphp-install.txt | 108 ++++++++++++------------------
docs/simplesamlphp-subversion.txt | 31 +++++++++
2 files changed, 74 insertions(+), 65 deletions(-)
create mode 100644 docs/simplesamlphp-subversion.txt
diff --git a/docs/simplesamlphp-install.txt b/docs/simplesamlphp-install.txt
index a3db54294..edb1dd337 100644
--- a/docs/simplesamlphp-install.txt
+++ b/docs/simplesamlphp-install.txt
@@ -21,6 +21,12 @@ This document is part of the simpleSAMLphp documentation suite.
* [simpleSAMLphp homepage](http://rnd.feide.no/simplesamlphp)
+Developement version
+--------------------
+
+This document is about the latest stable version of simpleSAMLphp.
+If you want to install the developement version, look at the instructions for installing simpleSAMLphp from subversion.
+
Prerequisites
-------------
@@ -43,73 +49,51 @@ What actual packages are required for the various extensions varies between diff
Download and install simpleSAMLphp
----------------------------------
-The most recent relase of simpleSAMLphp is found at [code.google.com/p/simplesamlphp/.](http://code.google.com/p/simplesamlphp/) To obtain a stable version, you may download the zipped `simplesamlphp` zip file listed under Featured Dowloads, or you may check out the last version includeing the most recent updates from the subversion repository.
-
-### Get a working copy of simpleSAMLphp from subversion
+The most recent relase of simpleSAMLphp is found at [code.google.com/p/simplesamlphp/](http://code.google.com/p/simplesamlphp/).
+To obtain the latest stable version, download the archive file listed under Featured Dowloads.
-Go to the directory where you want to install simpleSAMLphp:
+Go to the directory where you want to install simpleSAMLphp, and extract the archive file you just downloaded:
cd /var
-
-Then do a subversion checkout:
-
- svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp
-
-Using subversion, you can view logs and review changes to the
-files. To update the version you have checked out, enter:
-
- cd /var/simplesamlphp
- svn up
+ tar xzf simplesamlphp-1.x.y.tar.gz
+ mv simplesamlphp-1.x.y simplesamlphp
## Upgrading from a previous version of simpleSAMLphp
-*If you have downloaded a version from the subversion repository:*
+Extract the new version:
+
+ cd /var
+ tar xzf simplesamlphp-1.x.y.tar.gz
-Type, while located in the root folder of your simpleSAMLphp
-installation:
+Copy the configuration files from the previous version:
- svn update
+ cd /var/simplesamlphp-1.x.y
+ rm -rf config metadata
+ cp -rv ../simplesamlphp/config config
+ cp -rv ../simplesamlphp/metadata metadata
-*If you download and install the zipped version:*
+Replace the old version with the new version:
-- Make a backup of the `config` and the `metadata` directories.
-- Delete all files from your current simpleSAMLphp directory .
-- Unzip the new version in the simpleSAMLphp directory.
-- Install the backups of `config` and the `metadata` directories in the simpleSAMLphp directory.
+ cd /var
+ mv simplesamlphp simplesamlphp.old
+ mv simplesamlphp-1.x.y simplesamlphp
If the format of the config files or metadata has changed from your previous version of simpleSAMLphp (check the revision log), you may have to update your configuration and metadata after updating the simpleSAMLphp code:
+
### Upgrading configuration files
A good approach is to run a `diff` between your preivous `config.php` file and the new `config.php` file located in `config-templates/config.php`, and apply relevant modifications to the new template. This will ensure that all new entries in the latest version of config.php are included, as well as preserve your local modifications.
There is a link to a configuration check utility from the frontpage of your simpleSAMLphp installation page. The name of the link is "simpleSAMLphp configuration check". Then you will get a list of all configuration files in your `config/` directory. Click through the files, and you will get a report on superfluous and missing entries in the configuration file. What is done under the hood is that simpleSAMLphp looks up the `config-templates/` directory and compares to your real config. Although not all option is required to have in the configuration files, it's a good thumb rule to include them nontheless, so you simply see what configuration is possible.
+
### Upgrading metadata files
Most likely the metadata format is backwards compatible. If not, you should receive a very clear error message at startup indicating how and what you need to update. You should look through the metadata in the metadata-templates directory after the upgrade to see whether recommended defaults have been changed.
-
-
-Making configuration and metadata files
----------------------------------------
-
-### Tip
-
-You do not need to read this section if you are upgrading simpleSAMLphp from an earlier version, then see the section called ‹Upgrading from a previous version of simpleSAMLphp›.
-
-Configuration and metadata files are distributed as templates; you should make local copies to directories `config` and `metadata` and edit these copies to suit your local requirements. When you later upgrade, through a subversion `svn up` command or by installing a new zip file, your existing configuration data will not not be overwritten.
-
-Here are the steps you need to do to create local configuration files:
-
- cd /var/simplesamlphp
- cp -r config-templates/ config/
- cp -r metadata-templates/ metadata/
-
-
-
Configuring Apache
------------------
@@ -265,22 +249,33 @@ in an alternative way.
The SimpleSAMLphp code contains one folder named `simplesamlphp`. In this folder there are a lot of subfolders for library, metadata, configuration and much more. One of these folders is named `www`. This and *only this* folder should be exposed on the web. The reccomended configuration is to put the whole `simplesamlphp` folder outside the webroot, and then link in the `www` folder by using the `Alias` directive, as described in [the section called “Configuring Apache”](#sect.apacheconfig "Configuring Apache"). But this is not the only possible way.
-As an example, let's see how you can install simpleSAMLphp in your home directory on a shosted server.
+As an example, let's see how you can install simpleSAMLphp in your home directory on a shared hosting server.
-Check out simpleSAMLphp in your home directory, and move or symlink the www folder into the `public_html` folder.
+Extract the simpleSAMLphp archive in your home directory:
cd ~
- svn checkout [snipp] simplesamlphp
+ tar xzf simplesamlphp-1.x.y.tar.gz
+ mv simplesamlphp-1.x.y simplesamlphp
-Then you can try to make a symlink into the public\_html
-directory.
+Then you can try to make a symlink into the `public\_html` directory.
cd ~/public_html
ln -s ../simplesamlphp/www simplesaml
+Next, you need to update the configuration of paths in `simplesamlphp/config/config.php`:
+
+And, then we need to set the `baseurlpath` parameter to match the base path of the URLs to the content of your `www` folder:
+
+ 'baseurlpath' => '~andreas/simplesaml/',
+
+Now, you can go to the URL of your installation and check if things work:
+
+ http://yourcompany.com/~andreas/simplesaml/
+
+
### Tip
-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:
+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:
cd ~/public_html
mv ../simplesamlphp/www simplesaml
@@ -322,20 +317,3 @@ to:
### Note
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.
-
-Next, you need to update the configuration of paths in `simplesamlphp/config/config.php`:
-
-Set the `basedir` parameter to the path of your simplesamlphp folder:
-
- 'basedir' => '/home/andreas/simplesamlphp/',
-
-And, then we need to set the `baseurlpath` parameter to match the base path of the URLs to the content of your `www` folder:
-
- 'baseurlpath' => '~andreas/simplesaml/',
-
-Now, you can go to the URL of your installation and check if things work:
-
- http://yourcompany.com/~andreas/simplesaml/
-
-
-
diff --git a/docs/simplesamlphp-subversion.txt b/docs/simplesamlphp-subversion.txt
new file mode 100644
index 000000000..22690a921
--- /dev/null
+++ b/docs/simplesamlphp-subversion.txt
@@ -0,0 +1,31 @@
+simpleSAMLphp from Subversion
+=============================
+
+These are some notes about running simpleSAMLphp from subversion.
+
+Installing from Subversion
+--------------------------
+
+Go to the directory where you want to install simpleSAMLphp:
+
+ cd /var
+
+Then do a subversion checkout:
+
+ svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp
+
+Initialize configuration and metadata:
+
+ cd /var/simplesamlphp
+ cp -r config-templates/ config/
+ cp -r metadata-templates/ metadata/
+
+
+Upgrading
+---------
+
+Go to the root directory of your simpleSAMLphp installation:
+ cd /var/simplesamlphp
+
+Ask subversion to update to the latest version:
+ svn update
--
GitLab