[Pkg-owncloud-commits] [owncloud-doc] 35/110: Many corrections and enhancements to installation docs
David Prévot
taffit at moszumanska.debian.org
Fri Feb 6 21:10:31 UTC 2015
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository owncloud-doc.
commit 4435b648b3443e46c916197a16d4644b4be2f64d
Author: Carla Schroder <carla at owncloud.com>
Date: Wed Dec 24 14:00:55 2014 -0800
Many corrections and enhancements to installation docs
---
.../configuration/database_configuration.rst | 6 +-
.../images/install-wizard-advanced.png | Bin 107639 -> 38149 bytes
.../installation/images/install-wizard.png | Bin 86115 -> 27709 bytes
admin_manual/installation/installation_wizard.rst | 96 ++++++++++-----------
admin_manual/installation/linux_installation.rst | 16 ++--
admin_manual/installation/source_installation.rst | 76 ++++++++--------
admin_manual/installation/windows_installation.rst | 4 +-
admin_manual/maintenance/update.rst | 60 +++++++++++--
admin_manual/maintenance/upgrade.rst | 8 +-
9 files changed, 152 insertions(+), 114 deletions(-)
diff --git a/admin_manual/configuration/database_configuration.rst b/admin_manual/configuration/database_configuration.rst
index a164a2a..12b7803 100644
--- a/admin_manual/configuration/database_configuration.rst
+++ b/admin_manual/configuration/database_configuration.rst
@@ -3,14 +3,14 @@ Database Configuration
ownCloud requires a database in which administrative data is stored. The following databases are currently supported:
-* `MySQL <http://www.mysql.com/>`_ / MariaDB <https://mariadb.org/>`
-* `SQLite <http://www.sqlite.org/>`
+* `MySQL <http://www.mysql.com/>`_ / `MariaDB <https://mariadb.org/>`_
+* `SQLite <http://www.sqlite.org/>`_
* `PostgreSQL <http://www.postgresql.org/>`_
* `Oracle <http://www.oracle.com/>`_
The MySQL or MariaDB databases are the recommended database engines. However, because it is a file based database with the least administrative overhead, SQLite is chosen by default.
-.. note:: Because SQLite has some difficulties handling multiple users, we recommend that it be used only for single user ownCloud installations.
+.. note:: Because SQLite does not handle large datasets or large numbers of users well, we recommend that it be used only for single user ownCloud installations, or for simple testing setups.
Requirements
------------
diff --git a/admin_manual/installation/images/install-wizard-advanced.png b/admin_manual/installation/images/install-wizard-advanced.png
index b7f0b2f..02ad668 100644
Binary files a/admin_manual/installation/images/install-wizard-advanced.png and b/admin_manual/installation/images/install-wizard-advanced.png differ
diff --git a/admin_manual/installation/images/install-wizard.png b/admin_manual/installation/images/install-wizard.png
index 6eafca6..0273f1c 100644
Binary files a/admin_manual/installation/images/install-wizard.png and b/admin_manual/installation/images/install-wizard.png differ
diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst
index eecb2d9..7106505 100644
--- a/admin_manual/installation/installation_wizard.rst
+++ b/admin_manual/installation/installation_wizard.rst
@@ -1,21 +1,17 @@
Installation Wizard
--------------------
+===================
When ownCloud prerequisites are fulfilled and all ownCloud files are installed
-on the server, the last thing left to do for finishing the installation is
+on the server, the last step to complete the installation is
running the Installation Wizard.
* Open your web browser
* Navigate to your ownCloud instance.
* If you are installing ownCloud on the same machine as you are accessing the
- install wizard from, the url will be https://localhost/owncloud
+ install wizard from, the URL will be ``http://localhost/owncloud``, or ``https://localhost/owncloud`` if you have enabled SSL.
* If you are installing ownCloud on a different machine, you'll have to access
- it by its hostname or IP address, e.g. https://example.com/owncloud
- * Please take notice of the note at the end of the site if you're accessing
- your ownCloud instance via a different IP address or host name during setup
- than your users are going to use later on (or if your ownCloud instance
- should be accessible via more than one host name or IP address).
+ it by its hostname or IP address, e.g. ``http://example.com/owncloud``.
* If you are using a self-signed certificate, you will be presented with a
security warning about the issuer of the certificate not being trusted which
you can ignore.
@@ -23,33 +19,37 @@ running the Installation Wizard.
* You will be presented with the setup screen:
.. image:: images/install-wizard.png
+ :scale: 75%
Required Settings
~~~~~~~~~~~~~~~~~
-Under "create an admin account" you are requested to enter a username and
-password for the administrative user account. You can choose any username and
-password as you see fit, just make sure to remember it, you will need it later
-whenever you want to configure something for your ownCloud instance.
-Advanced Options
-~~~~~~~~~~~~~~~~
-* Advanced settings are available for configuring a different database or data
- directory than the default ones.
+Under ``create an admin account`` you must enter a username and
+password for the administrative user account. You may choose any username and
+password that you want.
+
+Storage & Database
+~~~~~~~~~~~~~~~~~~
+
+* Click ``Storage & Database`` to see all of your database options, and to optionally change the default data storage directory.
+
+* The database you want to use must already be installed, and you must have a database admin user and password.
+
+* Enter any arbitrary name for the Database name. This must be a database that does not already exist.
* If you are not using Apache as the web server, it is highly
recommended to configure the data directory to a location outside of
the document root. Otherwise all user data is potentially publicly
visible!
-* Show these additional options by clicking on "Advanced":
-
.. image:: images/install-wizard-advanced.png
+ :scale: 75%
-Database choice
-***************
+Database Choice
+~~~~~~~~~~~~~~~
* For a guideline on which database system to choose, and on pointers how to
- set them up for being available for php/ownCloud, see
+ set them up for being available for PHP/ownCloud, see
:doc:`../configuration/database_configuration`
* Note that you will only be able to choose among the PHP database connectors
@@ -59,61 +59,55 @@ Database choice
set up your ownCloud to use a specific one. So make sure to carefully
consider which database system to use.
-* When using MySQL or PostgreSQL you have two options regarding the database
+* When using MySQL/MariaDB or PostgreSQL you have two options regarding the database
name and user account you specify:
- * You can specify either an admin/root user, and the name of a database
+ * You can specify either an admin or the root user, and the name of a database
which does not yet exist. This lets ownCloud create its own database; it
will also create a database user account with restricted rights (with the
same username as you specified for the administrative user, plus an
``oc_`` prefix) and will use that for all subsequent database access.
- * Beware that there are restrictions as to what characters a database name
+ * There are restrictions as to what characters a database name
may or may not contain, see the
`MySQL Schema Object Names documentation`_ for details);
- * Make sure to choose a name under which no database exists yet
- * ownCloud will use the provided credentials and create its own user with
- permissions only on its own database.
-
- * You can enter the name of an existing database and the username/password
- of a user with permissions restricted to this one database only
-
- * You can create such a user yourself, e.g. via phpmyadmin.
- * This user shouldn't have permission to create a database.
- * It should have full permissions on the (existing) database with the
- name you specify.
-
Finish Installation
~~~~~~~~~~~~~~~~~~~
-* Once you've entered all settings, press "Finish Setup"
+
+* Once you've entered all settings, click "Finish Setup"
* ownCloud will set up your cloud according to the given settings
-* When its finished, it will log you in as administrative user and present the
+* When it's finished, it will log you in as administrative user and present the
"Welcome to ownCloud" screen.
+Trusted Domains
+~~~~~~~~~~~~~~~
-Note
-~~~~
ownCloud will take the URL used to access the Installation Wizard and insert
-that into the config.php file for the ‘trusted_domains’ setting.
-All needed domain names of the owncloud server go into the
-'trusted_domains' setting. No domain names of clients go there.
-
-Users will only be able to log into ownCloud when they point their browsers to a
-domain name listed in the ‘trusted_domains’ setting. An IPv4 address can be
-specified instead of a domain name.
-
-In the event that a load balancer is in place, there will be no issues, as long
+that into the ``config.php`` file for the ``trusted_domains`` setting.
+All needed domain names of the ownCloud server go into the
+``trusted_domains`` setting. Users will only be able to log into ownCloud when they point their browsers to a domain name listed in the ``trusted_domains`` setting. An IPv4 address can be
+specified instead of a domain name. A typical configuration looks like this::
+
+ 'trusted_domains' =>
+ array (
+ 0 => 'localhost',
+ 1 => 'server1',
+ 2 => '192.168.1.50',
+ ),
+
+In the event that a load balancer is in place there will be no issues as long
as it sends the correct X-Forwarded-Host header.
-It should be noted that the loopback address, '127.0.0.1', is whitelisted and
+The loopback address, ``127.0.0.1``, is whitelisted and
therefore users on the ownCloud server who access ownCloud with the loopback
interface will be able to successfully login.
In the event that an improper URL is used, the
following error will appear:
.. image:: images/untrusted-domain.png
-
+ :scale: 75%
+
For configuration examples, refer to the :file:`config/config.sample.php`
document.
diff --git a/admin_manual/installation/linux_installation.rst b/admin_manual/installation/linux_installation.rst
index 62962a5..f4bb430 100644
--- a/admin_manual/installation/linux_installation.rst
+++ b/admin_manual/installation/linux_installation.rst
@@ -1,18 +1,16 @@
-===================
-Linux Distributions
-===================
+===================================
+Preferred Linux Installation Method
+===================================
Supported Distribution Packages
-------------------------------
-Ready-to-use packages are available at `openSUSE Build Service`_ for a variety of Linux distributions. You must also install ``php5-libsmbclient`` from the `oBS repository`_.
+Ready-to-use packages are available at the ownCloud repository on the `openSUSE Build Service`_ for a variety of Linux distributions. Follow the instructions for your distro to add the oBS repository, download and install the repo signing key, and install ownCloud. Then run the Installation Wizard to complete your installation. (see :doc:`installation_wizard`).
-If your distribution is not listed please follow :doc:`source_installation`.
+If your distribution is not listed, your Linux distribution may maintain its own ownCloud packages, or you may prefer to install from source code (see :doc:`source_installation`).
.. _openSUSE Build Service: http://software.opensuse.org/download.html?project=isv:ownCloud:community&package=owncloud
-.. _oBS repository: http://software.opensuse.org/download.html?project=isv%3AownCloud%3Acommunity%3A7.0&package=php5-libsmbclient
-
Additional Installation Guides and Notes
----------------------------------------
@@ -28,8 +26,4 @@ See :doc:`selinux_configuration` for a suggested configuration for SELinux-enabl
.. _ownCloud, installation and setup: http://pclinuxoshelp.com/index.php/Owncloud,_installation_and_setup
-Installation Wizard
--------------------
-For setting up your ownCloud instance after installation, please refer to the
-:doc:`installation_wizard` section.
diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst
index 6982ef5..821cede 100644
--- a/admin_manual/installation/source_installation.rst
+++ b/admin_manual/installation/source_installation.rst
@@ -1,10 +1,9 @@
-Manual Installation
-===================
+Manual Installation on Linux
+============================
-If you do not want to use packages, here is how you setup ownCloud from
-scratch using a classic :abbr:`LAMP (Linux, Apache, MySQL, PHP)` setup:
+Installing ownCloud on Linux from the openSUSE Build Service packages is the preferred method (see :doc:`linux_installation`). These are maintained by ownCloud engineers, and you can use your package manager to keep your ownCloud server up-to-date.
-This document provides a complete walk-through for installing ownCloud on Ubuntu
+If there are no packages for your Linux distribution, or you prefer installing from sources, you can setup ownCloud from scratch using a classic LAMP stack (Linux, Apache, MySQL/MariaDB, PHP). This document provides a complete walk-through for installing ownCloud on Ubuntu
14.04 LTS Server with Apache and MySQL.
Prerequisites
@@ -12,8 +11,9 @@ Prerequisites
.. note:: This tutorial assumes you have terminal access to the machine you want
to install ownCloud on. Although this is not an absolute requirement,
- installation without it is highly likely to require contacting your
- hoster (e.g. for installing required modules).
+ installation without it is likely to require contacting your
+ hoster (e.g. for installing required modules). Consult the `PHP manual
+ <http://php.net/manual/en/extensions.php>`_ for information on modules. Your Linux distribution should have packages for all required modules.
To run ownCloud, your web server must have the following installed:
@@ -47,10 +47,9 @@ Database connectors (pick at least one):
* PHP module mcrypt (increases file encryption performance)
* PHP module openssl (required for accessing HTTPS resources)
-Required for specific apps (if you use the mentioned app, you must install that
-package):
+Required for specific apps:
-* PHP module ldap (for ldap integration)
+* PHP module ldap (for LDAP integration)
* smbclient (for SMB storage)
* PHP module ftp (for FTP storage)
@@ -59,7 +58,7 @@ Recommended for specific apps (*optional*):
* PHP module exif (for image rotation in pictures app)
* PHP module gmp (for SFTP storage)
-For enhanced performance (*optional* / select only one of the following):
+For enhanced server performance (*optional* / select only one of the following):
* PHP module apc
* PHP module apcu
@@ -69,14 +68,14 @@ For preview generation (*optional*):
* PHP module imagick
* avconv or ffmpeg
-* OpenOffice or libreOffice
+* OpenOffice or LibreOffice
**Remarks:**
* Please check your distribution, operating system or hosting partner
- documentation on how to install/enable these modules.
+ documentation on how to install and enable these modules.
-* Make sure your distribution's php version fulfils the version requirements
+* Make sure your distribution's PHP version fulfills the version requirements
specified above. If it doesn't, there might be custom repositories you can
use. If you are e.g. running Ubuntu 10.04 LTS, you can update your PHP using
a custom `PHP PPA <https://launchpad.net/~ondrej/+archive/php5>`_::
@@ -85,22 +84,20 @@ For preview generation (*optional*):
sudo apt-get update
sudo apt-get install php5
-* You don’t need any WebDAV support module for your web server (i.e. Apache’s
- mod_webdav) to access your ownCloud data via WebDAV. ownCloud has a built-in
- WebDAV server of its own.
+* You don’t need the WebDAV module for your web server (i.e. Apache’s
+ ``mod_webdav``) to access your ownCloud data via WebDAV. ownCloud has a built-in
+ WebDAV server of its own, SabreDAV.
Example installation on Ubuntu 14.04 LTS Server
-----------------------------------------------
-On a machine running a pristine Ubuntu 14.04 LTS server, you would install the
+On a machine running a pristine Ubuntu 14.04 LTS server, install the
required and recommended modules for a typical ownCloud installation, using
-Apache and MySQL by issuing the following commands in a terminal::
+Apache and MariaDB, by issuing the following commands in a terminal::
- apt-get install apache2 mysql-server libapache2-mod-php5
+ apt-get install apache2 mariadb-server libapache2-mod-php5
apt-get install php5-gd php5-json php5-mysql php5-curl
apt-get install php5-intl php5-mcrypt php5-imagick
-**Remarks:**
-
* This installs the packages for the ownCloud core system. If you are planning
on running additional apps, keep in mind that they might require additional
packages. See the Prerequisites section (above) for details.
@@ -110,13 +107,13 @@ Apache and MySQL by issuing the following commands in a terminal::
English. You might have to press a different key if you have a different
system language).
-* At the installation of the MySQL server, you will be prompted for a root
+* At the installation of the MySQL server, you will be prompted to create a root
password. Be sure to remember the password you enter there for later use
as you will need it during ownCloud database setup.
Now download the archive of the latest ownCloud version:
-* Navigate to the `ownCloud Installation Page <http://owncloud.org/install>`_.
+* Go to the `ownCloud Installation Page <http://owncloud.org/install>`_.
* Click the **Archive file for server owners** button.
* Click **Download Unix**.
* This downloads a file named owncloud-x.y.z.tar.bz2 (where
@@ -145,12 +142,20 @@ Now download the archive of the latest ownCloud version:
cp -r owncloud /path/to/webserver/document-root
where ``/path/to/webserver/document-root`` is replaced by the
- document root of your Web server. Typically, on Ubuntu systems this
+ document root of your Web server. On Ubuntu systems this
``/var/www/owncloud``, so your copying command is::
cp -r owncloud /var/www/
+
+Installation Wizard
+-------------------
+
+Finish setting up your ownCloud server by following
+the :doc:`installation_wizard`.
+
+After running the Installation Wizard your ownCloud installation is complete. However, you should perform the following steps to improve your server's security.
-Setting Secure Directory Permissions
+Setting Strong Directory Permissions
------------------------------------
Your HTTP user must own at least the ``config/``, ``data/``
@@ -169,8 +174,8 @@ Name it ``whoami.php`` and place it in your ``/var/www/html`` directory, and
then open it in a Web browser, for example ``http://localhost/whoami.php``. You
should see a single line in your browser page with the HTTP user name.
-.. note:: When using an NFS mount for the data directory, do not change
- ownership as above. The simple act of mounting the drive will set
+.. note:: When using an NFS mount for the data directory, do not change its
+ ownership from the default. The simple act of mounting the drive will set
proper permissions for ownCloud to write to the directory. Changing
ownership as above could result in some issues if the NFS mount is
lost.
@@ -194,7 +199,7 @@ as possible. These commands should be executed immediately after the initial ins
chown <http-user>:<http-user> /path/to/owncloud/apps/
chmod 750 /path/to/owncloud/apps/
-These strict permissions will prevent the Updater app from working. If you use the Updater app, it needs your whole
+These strict permissions will prevent the Updater app from working (see :doc:`../maintenance/update`). If you use the Updater app, it needs your whole
ownCloud directory to be owned by the http-user, like these examples:
* This example is for Ubuntu 14.04 LTS server::
@@ -213,7 +218,12 @@ ownCloud directory to be owned by the http-user, like these examples:
chown -R wwwrun:www /path/to/owncloud/
-After the Update app has run, you should re-apply the strict permissions.
+After the Update app has run, you should re-apply the strict permissions.
+
+SELinux
+-------
+
+See :doc:`selinux_configuration` for a suggested configuration for SELinux-enabled distributions such as Fedora and CentOS.
Apache is the recommended Web server.
@@ -393,11 +403,7 @@ Example config for Apache 2.4:
systemctl restart httpd.service
-Install Wizard
---------------
-
-Finish setting up your ownCloud server by following
-the :doc:`installation_wizard`.
+
Other Web Servers
-----------------
diff --git a/admin_manual/installation/windows_installation.rst b/admin_manual/installation/windows_installation.rst
index 295b241..02b60a9 100644
--- a/admin_manual/installation/windows_installation.rst
+++ b/admin_manual/installation/windows_installation.rst
@@ -20,8 +20,8 @@ Windows 7 and Windows Server 2008
.. note:: You must move the data directory outside of your public root (See
advanced installation settings)
-This section describes how to install ownCloud on Windows with :abbr:`IIS
-(Internet Information Services)`.
+This section describes how to install ownCloud on Windows with IIS
+(Internet Information Services).
These instructions assume that you have a standard, non-IIS enabled Windows
machine using Windows 7 or Server 2008. After enabling IIS, the procedures are
diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst
index 062e90d..c78bebc 100644
--- a/admin_manual/maintenance/update.rst
+++ b/admin_manual/maintenance/update.rst
@@ -28,8 +28,8 @@ Updater app or upgrading manually. You should still maintain regular backups
hosting. Larger installations should update ownCloud with their
Linux package managers or manually upgrade, and then complete the update
with the ``occ upgrade`` command, which is in the ``owncloud`` directory.
- Run ``occ help`` to see complete command options. ownCloud Enterprise
- Edition does not include the Updater app.
+ Run ``occ help`` to see complete command options. (ownCloud Enterprise
+ Edition does not include the Updater app.)
The Updater app performs these operations:
@@ -53,6 +53,7 @@ steps:
2. Even though the Update app backs up important directories, you should
always have your own current backups (See :doc:`backup` for details.)
+
3. Verify that the HTTP user on your system can write to your whole ownCloud
directory; on a stock Linux installation this is the ``www-data`` or
``apache`` user on systems that are running the Apache HTTP server. You can
@@ -62,10 +63,10 @@ steps:
``<?php echo exec('whoami'); ?>``
- Name it ``whoami.php`` and place it in your ``/srv/var/www/html directory``,
- and then open it in a Web browser, for example
+ Name it ``whoami.php`` and place it in your Web root directory, for example ``/var/www/html``, and then open it in a Web browser, for example
``http://servername/whoami.php``. You should see a single line in your
browser page with the HTTP user name.
+
4. Navigate to your 'Admin' page and click the 'Update Center' button under
Updater:
@@ -76,7 +77,10 @@ steps:
.. figure:: ../images/updater-3.png
6. Click Update, and carefully read the messages. If there are any problems it
- will tell you, otherwise you will see a message about checking your
+ will tell you. The most common issue is directory permissions; see :ref:`setting_strong_permissions`.
+
+
+ otherwise you will see a message about checking your
installation, making a backup, and moving files:
.. figure:: ../images/updater-4.png
@@ -98,9 +102,53 @@ steps:
Refresh your Admin page to verify your new version number.
-If the Update app fails, then you must update manually. See :doc:`upgrade` to
+If the Updater app fails, then you must update manually. See :doc:`upgrade` to
learn how to upgrade manually.
+.. _setting_strong_permissions:
+
+Setting Strong Permissions
+--------------------------
+
+The generic command to change ownership of all files and subdirectories in a
+directory is::
+
+ chown -R <http-user>:<http-user> /path/to/owncloud/
+
+For hardened security we highly recommend setting the permissions on your ownCloud directory as strictly
+as possible. These commands should be executed immediately after the initial installation::
+
+ chown -R root:root /path/to/owncloud/
+ chmod -R 755 /path/to/owncloud/
+ chown <http-user>:<http-user> /path/to/owncloud/config/config.php
+ chmod 750 /path/to/owncloud/config/config.php
+ chown -R <http-user>:<http-user> /path/to/owncloud/data/
+ chmod -R 750 /path/to/owncloud/data
+ chown root:root /path/to/owncloud/data/.htaccess
+ chmod 755 /path/to/owncloud/data/.htaccess
+ chown <http-user>:<http-user> /path/to/owncloud/apps/
+ chmod 750 /path/to/owncloud/apps/
+
+These strict permissions will prevent the Updater app from working, as it needs your whole
+ownCloud directory to be owned by the http-user, like these examples:
+
+* This example is for Ubuntu 14.04 LTS server::
+
+ chown -R www-data:www-data /var/www/owncloud
+
+* Arch Linux::
+
+ chown -R http:http /path/to/owncloud/
+
+* Fedora::
+
+ chown -R apache:apache /path/to/owncloud/
+
+* openSUSE::
+
+ chown -R wwwrun:www /path/to/owncloud/
+
+After the Updater app has run, you should re-apply the strict permissions.
diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst
index c27330e..6b54e04 100644
--- a/admin_manual/maintenance/upgrade.rst
+++ b/admin_manual/maintenance/upgrade.rst
@@ -17,12 +17,8 @@ You cannot skip major releases; for example, upgrading from 5.0 to 7.0. This is
unsupported, and you'll likely experience unpredictable results. It is best to
install all upgrades and updates in order.
-.. note:: If you installed ownCloud from your Linux distribution repositories
- using your package manager, then it is best to update/upgrade ownCloud using
- your package manager and staying in sync with your distro updates, rather
- than using the Updater app or upgrading manually. You should still
- maintain regular backups (see :doc:`backup`), and make a backup before every
- update/upgrade.
+.. note:: If you installed ownCloud from
+ `openSUSE Build Service <http://software.opensuse.org/download.html?project=isv:ownCloud:community&package=owncloud>`_, or from your Linux distribution repositories using your package manager, then it is best to update/upgrade ownCloud using your package manager rather than using the Updater app or upgrading manually. You should still maintain regular backups (see :doc:`backup`), and make a backup before every update/upgrade.
Manual Upgrade Procedure
------------------------
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git
More information about the Pkg-owncloud-commits
mailing list