Skip to content

docs(installation): update command-line installation guidance #15405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joshtrichards wants to merge 4 commits into
base: master
Choose a base branch
from
+99 −61
Open

docs(installation): update command-line installation guidance #15405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ae1d3bc
docs(installation): clarify command-line installation
joshtrichards Aug 2, 2026
aa5da6b
docs(occ): update maintenance install reference
joshtrichards Aug 2, 2026
22df52f
chore: fix sudo syntax in maintenance:install section
joshtrichards Aug 2, 2026
f24c947
chore: make occ syntax checker happy about command_line_installation
joshtrichards Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 56 additions & 28 deletions admin_manual/installation/command_line_installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,67 @@
============================
Installing from command line
============================
==============================
Install from the command line
==============================

It is now possible to install Nextcloud entirely from the command line. This is
convenient for scripted operations, headless servers, and sysadmins who prefer
the command line. There are three stages to installing Nextcloud via the command
line:
You can install Nextcloud without using the web-based Installation Wizard. This
is useful for automated deployments, headless servers, and administrators who
prefer the command line.

1. Download the Nextcloud code and unpack the tarball in the appropriate directories. (See :doc:`source_installation`.)
Before continuing, download and unpack the Nextcloud archive, configure the web
server and PHP, and create the database and database user when using MySQL,
MariaDB, PostgreSQL, or Oracle.

2. Change the ownership of your ``nextcloud`` directory to your HTTP user, like
this example for Debian/Ubuntu. You must run ``occ`` as your HTTP user; see
:ref:`http_user_label`::
For the complete manual-installation prerequisites, see
:doc:`source_installation`.

$ sudo chown -R www-data:www-data /var/www/nextcloud/
1. Ensure that the HTTP user has read and write access to all Nextcloud
directories. Changing ownership is the usual approach; for example, on
Debian/Ubuntu:

3. Use the ``occ`` command to complete your installation. This takes the place
of running the graphical Installation Wizard::
.. code-block:: console

$ cd /var/www/nextcloud/
$ sudo -E -u www-data php occ maintenance:install \
--database 'mysql' --database-name 'nextcloud' \
--database-user 'nextcloud' --database-pass 'password' \
--admin-user 'admin' --admin-pass 'password'
$ sudo chown -R www-data:www-data /var/www/nextcloud/

Note that you must change to the root Nextcloud directory, as in the example
above, to run ``occ maintenance:install``, or the installation will fail with
a PHP fatal error message.
Ownership is not strictly required. For example, where changing ownership is
not possible, add the HTTP user to the group that owns the directories and
ensure that they are group-writable. See :ref:`http_user_label`.

Supported databases are::
2. Use the ``occ`` command to complete the installation. This takes the place
of the graphical Installation Wizard. Run ``occ`` as the HTTP user so that
ownership and permissions remain consistent with the web server:

- sqlite (SQLite3 - Nextcloud Community edition only)
- mysql (MySQL/MariaDB)
- pgsql (PostgreSQL)
- oci (Oracle currently only possible if you contact us at https://nextcloud.com/enterprise as part of a subscription)
.. code-block:: console

See :ref:`command_line_installation_label` for more information.
$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install \
--database mysql --database-name nextcloud \
--database-user nextcloud \
--admin-user admin

This command prompts for the database and administrator passwords. For
unattended installations, specify ``--database-pass`` and ``--admin-pass``
using your deployment system's protected secret-handling mechanism. Avoid
exposing production passwords in shell history or process listings.

You can invoke ``occ`` from any directory when using its absolute path, as
in the example above. Alternatively, change to the Nextcloud root directory
and run ``sudo -E -u www-data php occ maintenance:install``.

Use ``--database-host`` and, if necessary, ``--database-port`` when the
database runs on another host. Use ``--data-dir`` to select a data directory
other than the default. To view all supported options, run:

.. code-block:: console

$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install --help

Supported databases are:

- ``sqlite`` (SQLite)
- ``mysql`` (MySQL/MariaDB)
- ``pgsql`` (PostgreSQL)
- ``oci`` (Oracle; contact `Nextcloud GmbH
<https://nextcloud.com/enterprise/>`_ for enterprise support)

The selected database requires its corresponding PHP extension or driver to be
installed and enabled.

See :ref:`command_line_installation_label` for more information.
76 changes: 43 additions & 33 deletions admin_manual/occ_system.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -885,45 +885,55 @@ These commands are only available before Nextcloud has been installed, after
you have unpacked the archive and copied Nextcloud into the appropriate
directories.

Display the available installation options::

sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install --help
Nextcloud is not installed - only a limited number of commands are available

Usage:
maintenance:install [options]

Options:
--database[=DATABASE] Supported database type [default: "sqlite"]
--database-name[=DATABASE-NAME] Name of the database
--database-host[=DATABASE-HOST] Hostname of the database [default: "localhost"]
--database-port[=DATABASE-PORT] Port of the database
--database-user[=DATABASE-USER] User name to connect to the database
--database-pass[=DATABASE-PASS] Password of the database user
--database-table-prefix[=...] Table prefix for every table in the database
--admin-user[=ADMIN-USER] User name of the admin account [default: "admin"]
--admin-pass[=ADMIN-PASS] Password of the admin account
--data-dir[=DATA-DIR] Path to data directory [default: "/var/www/nextcloud/data"]

This example installs Nextcloud with a MySQL database::

sudo -E -u www-data php occ maintenance:install \
--database mysql \
--database-name nextcloud \
--database-host 127.0.0.1 \
--database-user nextcloud \
--database-pass secret \
--admin-user admin \
--admin-pass password
Display the available installation options:

.. code-block:: console

$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install --help
Nextcloud is not installed - only a limited number of commands are available

Usage:
maintenance:install [options]

Options:
--database[=DATABASE] Supported database type [default: "sqlite"]
--database-name[=DATABASE-NAME] Name of the database
--database-host[=DATABASE-HOST] Hostname of the database [default: "localhost"]
--database-port[=DATABASE-PORT] Port the database is listening on
--database-user[=DATABASE-USER] Login for database connection
--database-pass[=DATABASE-PASS] Password of the database login
--database-table-space[=DATABASE-TABLE-SPACE]
Table space of the database (``oci`` only)
--disable-admin-user Disable the creation of an administrator login
--admin-user[=ADMIN-USER] Login for initial administrator account [default: "admin"]
--admin-pass[=ADMIN-PASS] Password for initial administrator login
--admin-email[=ADMIN-EMAIL] E-Mail to associate with the initial administrator login
--data-dir[=DATA-DIR] Path to data directory
--password-salt[=PASSWORD-SALT] Password salt; generated if not provided (ADVANCED)
--server-secret[=SERVER-SECRET] Server secret; generated if not provided (ADVANCED)

This example installs Nextcloud with a MySQL database. ``occ`` prompts for
the database and administrator passwords:

.. code-block:: console

$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install \
--database mysql \
--database-name nextcloud \
--database-host 127.0.0.1 \
--database-user nextcloud \
--admin-user admin
What is the password to access the database with user <nextcloud>?
What is the password you like to use for the admin account <admin>?
Nextcloud was successfully installed

Supported databases:

* ``sqlite`` — SQLite (community edition only; not recommended for production)
* ``sqlite`` — SQLite (not recommended for production usage)
* ``mysql`` — MySQL or MariaDB
* ``pgsql`` — PostgreSQL
* ``oci`` — Oracle (Nextcloud Enterprise only)

* ``oci`` — Oracle; contact `Nextcloud GmbH
<https://nextcloud.com/enterprise/>`_ for enterprise support

.. _command_line_upgrade_label:

Expand Down
Loading