From 8b2f39972fdd679c55288cd9ef0b37c0664db4ee Mon Sep 17 00:00:00 2001 From: cytopia Date: Wed, 8 Aug 2018 09:31:36 +0200 Subject: [PATCH] Fixes #341 - Documentation: Install CraftCMS --- README.md | 2 + docs/_includes/links/examples.rst | 6 + docs/examples/setup-craftcms.rst | 231 ++++++++++++++++++ .../create-your-first-project.rst | 1 + docs/img/logo_fw/craftcms.png | Bin 0 -> 2670 bytes docs/index.rst | 1 + docs/support/faq.rst | 6 + 7 files changed, 247 insertions(+) create mode 100644 docs/examples/setup-craftcms.rst create mode 100644 docs/img/logo_fw/craftcms.png diff --git a/README.md b/README.md index 3f9a5b21..b9d97f06 100644 --- a/README.md +++ b/README.md @@ -521,6 +521,7 @@ As far as tested there are no limitations and you can use any Framework or CMS j Devilbox Devilbox +Devilbox Devilbox Devilbox Devilbox @@ -538,6 +539,7 @@ As far as tested there are no limitations and you can use any Framework or CMS j > **Documentation:**
> [Setup CakePHP](https://devilbox.readthedocs.io/en/latest/examples/setup-cakephp.html) | > [Setup CodeIgniter](https://devilbox.readthedocs.io/en/latest/examples/setup-codeigniter.html) | +> [Setup CraftCMS](https://devilbox.readthedocs.io/en/latest/examples/setup-craftcms.html) | > [Setup Drupal](https://devilbox.readthedocs.io/en/latest/examples/setup-drupal.html) | > [Setup Joomla](https://devilbox.readthedocs.io/en/latest/examples/setup-joomla.html) | > [Setup Laravel](https://devilbox.readthedocs.io/en/latest/examples/setup-laravel.html) | diff --git a/docs/_includes/links/examples.rst b/docs/_includes/links/examples.rst index 87726129..407e2eaa 100644 --- a/docs/_includes/links/examples.rst +++ b/docs/_includes/links/examples.rst @@ -10,6 +10,12 @@ Official CodeIgniter Documentation +.. |ext_lnk_example_craftcms_documentation| raw:: html + + + Official CraftCMS Documentation + + .. |ext_lnk_example_drupal_documentation| raw:: html diff --git a/docs/examples/setup-craftcms.rst b/docs/examples/setup-craftcms.rst new file mode 100644 index 00000000..56d90b34 --- /dev/null +++ b/docs/examples/setup-craftcms.rst @@ -0,0 +1,231 @@ +.. include:: /_includes/all.rst + +.. _example_setup_craftcms: + +************** +Setup CraftCMS +************** + +This example will use ``composer`` to install CraftCMS from within the Devilbox PHP container. + +After completing the below listed steps, you will have a working CraftCMS setup ready to be +served via http and https. + +.. seealso:: |ext_lnk_example_craftcms_documentation| + + +**Table of Contents** + +.. contents:: :local: + + +Overview +======== + +The following configuration will be used: + ++--------------+--------------------------+-------------+------------+-----------------------------------------------+ +| Project name | VirtualHost directory | Database | TLD_SUFFIX | Project URL | ++==============+==========================+=============+============+===============================================+ +| my-craft | /shared/httpd/my-craft | my_craft | loc | http://my-craft.loc |br| https://my-craft.loc | ++--------------+--------------------------+-------------+------------+-----------------------------------------------+ + +.. note:: + * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``. + * On your host operating system, projects are by default in ``./data/www/`` inside the + Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`. + + +Walk through +============ + +It will be ready in eight simple steps: + +1. Enter the PHP container +2. Create a new VirtualHost directory +3. Install CraftCMS via ``composer`` +4. Symlink webroot directory +5. Add MySQL database +6. Setup DNS record +7. Run setup wizard +8. Visit http://my-craft.loc in your browser + + +1. Enter the PHP container +-------------------------- + +All work will be done inside the PHP container as it provides you with all required command line +tools. + +Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to +enter the running PHP container. + +.. code-block:: bash + + host> ./shell.sh + +.. seealso:: + * :ref:`enter_the_php_container` + * :ref:`work_inside_the_php_container` + * :ref:`available_tools` + + +2. Create new vhost directory +----------------------------- + +The vhost directory defines the name under which your project will be available. |br| +( ``.TLD_SUFFIX`` will be the final URL ). + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ mkdir my-craft + +.. seealso:: :ref:`env_tld_suffix` + + +3. Install CraftCMS +------------------- + +Navigate into your newly created vhost directory and install CraftCMS with ``composer``. + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ cd my-craft + devilbox@php-7.0.20 in /shared/httpd/my-craft $ composer create-project craftcms/craft craftcms + +How does the directory structure look after installation: + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-craft $ tree -L 1 + . + └── craftcms + + 1 directory, 0 files + + +4. Symlink webroot +------------------ + +Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every +project's document root to be in ``/htdocs/``. This is the path where it will serve +the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should +be found. + +Some frameworks however provide its actual content in nested directories of unknown levels. +This would be impossible to figure out by the web server, so you manually have to symlink it back +to its expected path. + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-craft $ ln -s craftcms/web/ htdocs + +How does the directory structure look after symlinking: + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-craft $ tree -L 1 + . + ├── craftcms + └── htdocs -> craftcms/web + + 2 directories, 0 files + +As you can see from the above directory structure, ``htdocs`` is available in its expected +path and points to the frameworks entrypoint. + + +5. Add MySQL Database +--------------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-craft $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_craft CHARACTER SET utf8 COLLATE utf8_unicode_ci;' + + +6. DNS record +------------- + +If you **have** Auto DNS configured already, you can skip this section, because DNS entries will +be available automatically by the bundled DNS server. + +If you **don't have** Auto DNS configured, you will need to add the following line to your +host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows): + +.. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 my-craft.loc + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` + + +7. Run setup wizard +------------------- + +After everything is setup, you need to run the setup wizard. CraftCMS bundles a commandline tool +that you can use. + +7.1 Via command line tool +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-craft $ php craftcms/craft setup + + Which database driver are you using? [mysql,pgsql,?]: mysql + Database server name or IP address: [localhost] 127.0.0.1 + Database port: [3306] + Database username: [root] + Database password: + Database name: my_craft + Database table prefix: + Testing database credentials... success! + Saving database credentials to your .env file... done + + Install Craft now? (yes|no) [yes]: + + Username: [admin] + Email: admin@devilbox.org + Password: + Confirm: + Site name: craftcms + Site URL: [@web] my-craft.loc + Site language: [en-US] + + ... + + *** installed Craft successfully (time: 14.660s) + + +7.2 Via browser +^^^^^^^^^^^^^^^ + +If you do not feel too comfortable on the command line, you can also run the setup wizard via +the browser. See their official documentation for screenshots. + +.. seealso:: |ext_lnk_example_craftcms_documentation| + +To open the setup wizard, visit: http://my-craft.loc/admin/install or https://my-craft.loc/admin/install + +* Driver: ``MySQL`` +* Server: ``127.0.0.1`` +* Port: ``3306`` +* Username: ``root`` +* Password: your MySQL password +* Database Name: ``my_craft`` +* Prefix: leave empty + +.. important:: When chosing the Database server, use ``127.0.0.1`` as the hostname. + + +8. Open your browser +-------------------- + +All set now, you can visit http://my-craft.loc or https://my-craft.loc in your browser. + +.. seealso:: :ref:`setup_valid_https` diff --git a/docs/getting-started/create-your-first-project.rst b/docs/getting-started/create-your-first-project.rst index 5e447cc1..6020a01e 100644 --- a/docs/getting-started/create-your-first-project.rst +++ b/docs/getting-started/create-your-first-project.rst @@ -196,6 +196,7 @@ their articles: * :ref:`example_setup_cakephp` * :ref:`example_setup_codeigniter` + * :ref:`example_setup_craftcms` * :ref:`example_setup_drupal` * :ref:`example_setup_joomla` * :ref:`example_setup_laravel` diff --git a/docs/img/logo_fw/craftcms.png b/docs/img/logo_fw/craftcms.png new file mode 100644 index 0000000000000000000000000000000000000000..fd289fc80114008caacaf8f90a55e7fc3366d819 GIT binary patch literal 2670 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 literal 0 HcmV?d00001 diff --git a/docs/index.rst b/docs/index.rst index c60b5033..55319b87 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -139,6 +139,7 @@ host is ready to be served with your custom domain. examples/setup-cakephp examples/setup-codeigniter + examples/setup-craftcms examples/setup-drupal examples/setup-joomla examples/setup-laravel diff --git a/docs/support/faq.rst b/docs/support/faq.rst index cae39dde..4e81cb17 100644 --- a/docs/support/faq.rst +++ b/docs/support/faq.rst @@ -160,6 +160,12 @@ Does it work with Codeigniter? Yes, see :ref:`example_setup_codeigniter` +Does it work with CraftCMS? +--------------------------- + +Yes, see :ref:`example_setup_craftcms` + + Does it work with Drupal? -------------------------