[Pkg-owncloud-commits] [owncloud-doc] 01/14: Installation wizard / database hint consolidation & fixes
David Prévot
taffit at moszumanska.debian.org
Wed Jun 11 20:20:23 UTC 2014
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository owncloud-doc.
commit 46f1d032b3c080f0767e0fba54c874555b356051
Author: RandolfCarter <RandolphCarter at fantasymail.de>
Date: Sun Jun 1 18:42:09 2014 +0200
Installation wizard / database hint consolidation & fixes
---
.../configuration/configuration_database.rst | 98 +++++++++++++-----
.../images/install-wizard-advanced.png | Bin 0 -> 117759 bytes
.../installation/images/install-wizard.png | Bin 0 -> 87514 bytes
admin_manual/installation/installation_linux.rst | 3 +-
admin_manual/installation/installation_source.rst | 106 +++----------------
admin_manual/installation/installation_windows.rst | 21 ++--
admin_manual/installation/installation_wizard.rst | 115 +++++++++++++++++++++
7 files changed, 210 insertions(+), 133 deletions(-)
diff --git a/admin_manual/configuration/configuration_database.rst b/admin_manual/configuration/configuration_database.rst
index ad42756..7d2d527 100644
--- a/admin_manual/configuration/configuration_database.rst
+++ b/admin_manual/configuration/configuration_database.rst
@@ -1,22 +1,34 @@
MySQL/Postgres/SQLite Support
=============================
-ownCloud requires a database where administrative data will be held. Four different database types are currently
-supported, `MySQL <http://www.mysql.com/>`_, `MariaDB <https://mariadb.org/>`_, `SQLite <http://www.sqlite.org/>`_,
-and `PostgreSQL <http://www.postgresql.org/>`_. MySQL or MariaDB are the recommended database engines. By default
-SQLite is chosen because it is a file based database with the least administrative overhead.
+ownCloud requires a database where administrative data will be held. Four
+different database types are currently supported,
+`MySQL <http://www.mysql.com/>`_ / `MariaDB <https://mariadb.org/>`_,
+`SQLite <http://www.sqlite.org/>`_, `PostgreSQL <http://www.postgresql.org/>`_
+and `Oracle <http://www.oracle.com/>`_. MySQL or MariaDB are the recommended
+database engines. By default SQLite is chosen because it is a file based
+database with the least administrative overhead.
-.. note:: Because SQLite handles multiple users very badly SQLite is only recommended for single user ownCloud installations
+.. note:: Because SQLite handles multiple users very badly SQLite is only
+ recommended for single user ownCloud installations.
Requirements
------------
-If you decide to use MySQL, MariaDB, or PostgreSQL you need to install and set-up the
-database first. These steps will not be covered by this description as they are easy to find elsewhere.
+If you decide to use MySQL / MariaDB, PostgreSQL or Oracle, you need to install
+and set up the server software first. These steps will not be covered by this
+description as they are easy to find elsewhere.
Parameters
----------
+.. note:: For setting up ownCloud to use any of these databases, use the
+ :doc:`../installation/installation_wizard`.
+ You usually don't need to edit the respective values in the
+ :file:`config/config.php`, just in special cases e.g. if you want to
+ connect your ownCloud instance to a database created by a previous
+ installation of ownCloud.
+
MySQL/MariaDB Database
~~~~~~~~~~~~~~~~~~~~~~
@@ -69,8 +81,11 @@ You can quit the prompt by entering::
quit
-In the ownCloud configuration you need to set the hostname on which the
-database is running and a valid username and password to access it.
+An ownCloud configured with MySQL would contain the hostname on which the
+database is running, a valid username and password to access it, and the
+name of the database. The :file:`config/config.php` as created by the
+:doc:`installation/installation_wizard` would therefore contain entries like
+this:
.. code-block:: php
@@ -81,7 +96,7 @@ database is running and a valid username and password to access it.
"dbuser" => "username",
"dbpassword" => "password",
"dbhost" => "localhost",
- "dbtableprefix" => "",
+ "dbtableprefix" => "oc_",
SQLite Database
~~~~~~~~~~~~~~~
@@ -99,10 +114,12 @@ It is not necessary to create a database and a database user in advance
because this will automatically be done by ownCloud when you login for the
first time.
-In the ownCloud configuration in :file:`config/config.php` you need to set at least the **datadirectory** parameter to
-the directory where your data and database should be stored. Note that for the PDO SQLite driver this directory must
-be writable (this is recommended for ownCloud anyway). No authentication is required to access the database therefore
-most of the default parameters could be taken as is:
+An ownCloud configured to use sqlite only needs to contain the reference to a
+writable data directory (which is required for the rest of ownCloud's operation
+as well anyway). The :file:`config/config.php` as created by the
+:doc:`installation/installation_wizard` could therefore contain entries like
+this:
+
.. code-block:: php
@@ -114,7 +131,7 @@ most of the default parameters could be taken as is:
"dbpassword" => "",
"dbhost" => "",
"dbtableprefix" => "",
- "datadirectory" => "/www/htdocs/owncloud/data",
+ "datadirectory" => "/var/www/html/owncloud/data",
PostgreSQL Database
~~~~~~~~~~~~~~~~~~~
@@ -158,10 +175,11 @@ You can quit the prompt by entering::
\q
-In the ownCloud configuration you need to set the hostname on which the
-database is running and a valid username (and sometimes a password) to
-access it. If the database has been installed on the same server as
-ownCloud a password is very often not required to access the database.
+An ownCloud configured with PostgreSQL would contain the hostname on which the
+database is running, a valid username and password to access it, and the
+name of the database. The :file:`config/config.php` as created by the
+:doc:`installation/installation_wizard` would therefore contain entries like
+this:
.. code-block:: php
@@ -172,7 +190,7 @@ ownCloud a password is very often not required to access the database.
"dbuser" => "username",
"dbpassword" => "password",
"dbhost" => "localhost",
- "dbtableprefix" => "",
+ "dbtableprefix" => "oc_",
Oracle Database
~~~~~~~~~~~~~~~
@@ -231,10 +249,11 @@ You can quit the prompt by entering::
exit
-In the ownCloud configuration you need to set the hostname on which the
-database is running and a valid username and password to
-access it. If the database has been installed on the same server as
-ownCloud to config file could look like this:
+An ownCloud configured with Oracle would contain the hostname on which the
+database is running, a valid username and password to access it, and the
+name of the database. The :file:`config/config.php` as created by the
+:doc:`installation/installation_wizard` would therefore contain entries like
+this:
.. code-block:: php
@@ -246,16 +265,18 @@ ownCloud to config file could look like this:
"dbpassword" => "password",
"dbhost" => "localhost",
-.. note:: This example assumes you are running an Oracle Express Edition on ``localhost``. The ``dbname`` is the name
-of the Oracle instance. For Oracle Express Edition it is always ``XE``.
+.. note:: This example assumes you are running an Oracle Express Edition on
+ ``localhost``. The ``dbname`` is the name of the Oracle instance.
+ For Oracle Express Edition it is always ``XE``.
Trouble Shooting
----------------
-How can I find out if my MySQL/PostgreSQL server is reachable?
+How can I find out if my MySQL/PostgreSQL server is reachable?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Use the ping command to check the server availability::
+To check the server's network availability, use the ping command on
+the server's host name (db.server.com in this example)::
ping db.server.dom
@@ -265,6 +286,9 @@ Use the ping command to check the server availability::
64 bytes from your-server.local.lan (192.168.1.10): icmp_req=1 ttl=64 time=3.64 ms
64 bytes from your-server.local.lan (192.168.1.10): icmp_req=2 ttl=64 time=0.055 ms
64 bytes from your-server.local.lan (192.168.1.10): icmp_req=3 ttl=64 time=0.062 ms
+
+For a more detailed check whether the access to the database server software
+itself works correctly, see the next question.
How can I find out if a created user can access a database?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -284,8 +308,16 @@ command line interface:
**MySQL**::
+Assuming the database server is installed on the same sytem you're running,
+the command from, use:
+
mysql -uUSERNAME -p
+To acess a MySQL installation on a different machine, add the -h option with
+the respective host name:
+
+ mysql -uUSERNAME -p -h HOSTNAME
+
::
mysql> SHOW VARIABLES LIKE "version";
@@ -299,8 +331,16 @@ command line interface:
**PostgreSQL**::
+Assuming the database server is installed on the same sytem you're running
+the command from, use:
+
psql -Uusername -downcloud
+To acess a MySQL installation on a different machine, add the -h option with
+the respective host name:
+
+ psql -Uusername -downcloud -h HOSTNAME
+
::
postgres=# SELECT version();
@@ -310,6 +350,8 @@ command line interface:
**Oracle**::
+On the machine where your Oracle database is installed, type
+
sqlplus username
::
diff --git a/admin_manual/installation/images/install-wizard-advanced.png b/admin_manual/installation/images/install-wizard-advanced.png
new file mode 100644
index 0000000..6157247
Binary files /dev/null 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
new file mode 100644
index 0000000..be77cce
Binary files /dev/null and b/admin_manual/installation/images/install-wizard.png differ
diff --git a/admin_manual/installation/installation_linux.rst b/admin_manual/installation/installation_linux.rst
index 7a8a2ad..a266134 100644
--- a/admin_manual/installation/installation_linux.rst
+++ b/admin_manual/installation/installation_linux.rst
@@ -30,4 +30,5 @@ or else the installation process might fail.
Follow the wizard to complete your installation
***********************************************
-For setting up your ownCloud instance after installation, please refer to the :ref:`install-wizard` section.
+For setting up your ownCloud instance after installation, please refer to the
+:doc:`installation_wizard` section.
diff --git a/admin_manual/installation/installation_source.rst b/admin_manual/installation/installation_source.rst
index c4def11..ced6fd5 100644
--- a/admin_manual/installation/installation_source.rst
+++ b/admin_manual/installation/installation_source.rst
@@ -585,96 +585,25 @@ Microsoft Internet Information Server (IIS)
See :doc:`installation_windows` for further instructions.
-.. _install-wizard:
-
-Follow the Install Wizard
+Install 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
- * 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
- * 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.
-
-* You will be presented with the setup screen
-* Enter username and password for the administrative user account
-* Expand Advanced options to choose a data folder and the database system
-
-* If you are not using Apache as the web server, please set the data directory
- to a location outside of the document root.
-
-* If following the Ubuntu-Apache-MySQL walk-through:
-
- * choose MySQL as Database backend (you might not be presented with any other
- choice if you haven't installed any other database systems).
- * As Database host, enter ``localhost``.
- * As Database user enter ``root``.
- * As Database password, enter the password you entered during installation of
- the MySQL server package.
- * As Database name, enter an arbitrary name as you see fit
-
- * Beware that 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.
-
-* In general, you have the following choices regarding the database:
-
- * For basic installs we recommend SQLite as it is easy to setup (ownCloud will do
- it for you). The performance when using sqlite is however inferior to the two
- other options.
- * For larger installs you should use MySQL or PostgreSQL.
- * Note that you will only be able to choose among the php database connectors
- which are actually installed on the system (see package requirements above).
- * Further, it is not easily possible to migrate to another database system
- once you have 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
- name and user account you specify:
-
- * You can specify either an admin/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.
- * You can enter the name of an existing database and the username/password
- of a user with restricted permissions
-
- * 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.
-
-* Press "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
- "Welcome to ownCloud" screen.
-
-Note
-~~~~
-When the initial ownCloud configuration is performed, ownCloud will take the URL used to access it and insert that
-the config.php file under the ‘trusted_domains’ header.
-
-Users will only be able to log into ownCloud when the addressed URL is as stated in the ‘trusted_domans’ header
-in the config.php file.
-
-In the event that a load balancer is in place, as long as it sends the correct X-Forwarded-Host header, there will
-be no issues.
-
-It should be noted that the loopback address, 127.0.0.1, is white labeled and therefore users on the ownCloud
-server who access ownCloud with the loopback will successfully login.
-In the event that an improper URL is used, the following error will appear:
-
-.. image:: images/untrusted-domain.png
-
-For configuration examples, refer to the config.php document.
+The last thing to do is to click through the installation wizard.
+
+Here are some guidelines for the values to enter there if following the
+Ubuntu-Apache-MySQL walk-through:
+
+* Make sure to click the "Advanced" Button to see the database settings
+
+* Choose MySQL as Database backend (you might not be presented with any other
+choice if you haven't installed any other database systems).
+* As Database host, enter ``localhost``.
+* As Database user enter ``root``.
+* As Database password, enter the password you entered during installation of
+the MySQL server package.
+* As Database name, enter an arbitrary name as you see fit
+
+Continue by following the :doc:`installation_wizard`.
.. _PHP PPA: https://launchpad.net/~ondrej/+archive/php5
@@ -682,4 +611,3 @@ For configuration examples, refer to the config.php document.
.. _options for free SSL certificates: https://www.sslshopper.com/article-free-ssl-certificates-from-a-free-certificate-authority.html
.. _github gist for further instructions: https://gist.github.com/2200407
.. _Nginx HTTP SSL Module documentation: http://wiki.nginx.org/HttpSslModule
-.. _MySQL Schema Object Names documentation: http://dev.mysql.com/doc/refman/5.5/en/identifiers.html
diff --git a/admin_manual/installation/installation_windows.rst b/admin_manual/installation/installation_windows.rst
index 9a594ff..5806bf6 100644
--- a/admin_manual/installation/installation_windows.rst
+++ b/admin_manual/installation/installation_windows.rst
@@ -155,7 +155,7 @@ This part installs MySQL on your Windows machine.
#. Select the modify security settings box on the next page, and enter a
password you will remember. You will need this password when you configure
ownCloud.
-#. Uncheck **enable** root access from remote machines” for security reasons.
+#. Uncheck “enable root access from remote machines” for security reasons.
#. Click execute, and wait while the instance is created and launched.
#. Click Finish when this is all complete.
@@ -196,20 +196,11 @@ Installing ownCloud
button “to change permissions, click edit”.
6. Select the “users” user from the list, and check the box “write”.
7. Apply these settings and close out.
-8. Now open your browser and go to http://localhost/owncloud (or localhost if it
- is installed in the root www directory). This should bring up the ownCloud
- configuration page.
-9. At this page, you enter your desired ownCloud user name and password for the
- administrator, and expand the little arrow.
-10. Select MySQL as the database, and enter your MySQL database user name,
- password and desired instance name – use the user name and password you setup
- for MySQL earlier in step 3, and pick any name for the database instance.
-
-.. note:: The ownCloud admin password and the MySQL password CANNOT be the same
- in any way.
-
-11. Click next, and ownCloud should have you logged in as the admin user, and
- you can get started exploring ownCloud, creating other users and more!
+
+Continue by following the :doc:`installation_wizard`.
+Select MySQL as the database, and enter your MySQL database user name,
+password and desired instance name – use the user name and password you setup
+during MySQL installation, and pick any name for the database instance.
Ensure Proper HTTP-Verb handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst
new file mode 100644
index 0000000..337873e
--- /dev/null
+++ b/admin_manual/installation/installation_wizard.rst
@@ -0,0 +1,115 @@
+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
+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
+ * 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
+ * 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.
+
+* You will be presented with the setup screen:
+
+.. image:: images/install-wizard.png
+
+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.
+
+* 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
+
+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
+ :doc:`../configuration/configuration_database`
+
+* Note that you will only be able to choose among the php database connectors
+ which are actually installed on the system.
+
+* It is not easily possible to migrate to another database system once you have
+ 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
+ name and user account you specify:
+
+ * You can specify either an admin/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
+ 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"
+* 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
+ "Welcome to ownCloud" screen.
+
+
+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.
+
+Users will only be able to log into ownCloud when they are using a domain name
+listed in the ‘trusted_domans’ setting.
+
+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
+therefore users on the ownCloud server who access ownCloud with the loopback
+will successfully login. In the event that an improper URL is used, the
+following error will appear:
+
+.. image:: images/untrusted-domain.png
+
+For configuration examples, refer to the :file:`config/config.sample.php`
+document.
+
+
+
+.. _MySQL Schema Object Names documentation: http://dev.mysql.com/doc/refman/5.5/en/identifiers.html
--
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