kopia lustrzana https://github.com/wagtail/wagtail
Started restructuring getting started docs
Karl Hobley
rodzic
9072274a01
commit
5d6aa0c6ca
|
|
@ -11,7 +11,7 @@ The ``wagtail start`` command
|
|||
|
||||
The easiest way to start a new project with wagtail is to use the ``wagtail start`` command. This command is installed into your environment when you install Wagtail (see: :doc:`installation`).
|
||||
|
||||
The command works the same way as ``django-admin.py startproject`` except that the produced project is pre-configured for Wagtail. It also contains some useful extras which we will look at in the next section.
|
||||
The command works the same way as ``django-admin.py startproject`` except that the produced project is pre-configured for Wagtail. It also contains some useful extras which are documented :doc:`here <getting_started/the_template>`.
|
||||
|
||||
To create a project, cd into a directory where you would like to create your project and run the following command:
|
||||
|
||||
|
|
@ -20,129 +20,25 @@ To create a project, cd into a directory where you would like to create your pro
|
|||
wagtail start mysite
|
||||
|
||||
|
||||
The project
|
||||
===========
|
||||
Running it
|
||||
==========
|
||||
|
||||
Lets look at what ``wagtail start`` created::
|
||||
TODO
|
||||
|
||||
mysite/
|
||||
core/
|
||||
static/
|
||||
templates/
|
||||
base.html
|
||||
404.html
|
||||
500.html
|
||||
mysite/
|
||||
settings/
|
||||
base.py
|
||||
dev.py
|
||||
production.py
|
||||
manage.py
|
||||
vagrant/
|
||||
provision.sh
|
||||
Vagrantfile
|
||||
readme.rst
|
||||
requirements.txt
|
||||
|
||||
|
||||
The "core" app
|
||||
----------------
|
||||
|
||||
Location: ``/mysite/core/``
|
||||
|
||||
This app is here to help get you started quicker by providing a ``HomePage`` model with migrations to create one when you first setup your app.
|
||||
cd mysite
|
||||
pip install -r requirements.txt
|
||||
python manage.py migrate
|
||||
python manage.py createsuperuser
|
||||
python manage.py runserver
|
||||
|
||||
|
||||
Default templates and static files
|
||||
----------------------------------
|
||||
|
||||
Location: ``/mysite/core/templates/`` and ``/mysite/core/static/``
|
||||
|
||||
The templates directory contains ``base.html``, ``404.html`` and ``500.html``. These files are very commonly needed on Wagtail sites to they have been added into the template.
|
||||
|
||||
The static directory contains an empty javascript and sass file. Wagtail uses ``django-compressor`` for compiling and compressing static files. For more information, see: `Django Compressor Documentation <http://django-compressor.readthedocs.org/en/latest/>`_
|
||||
Your site is now accessible at http://localhost:8000, with the admin backend available at http://localhost:8000/admin/ .
|
||||
|
||||
|
||||
Vagrant configuration
|
||||
---------------------
|
||||
Using Vagrant
|
||||
-------------
|
||||
|
||||
Location: ``/Vagrantfile`` and ``/vagrant/``
|
||||
|
||||
If you have Vagrant installed, these files let you easily setup a development environment with PostgreSQL and Elasticsearch inside a virtual machine.
|
||||
|
||||
See below section `With Vagrant`_ for info on how to use Vagrant in development
|
||||
|
||||
If you do not want to use Vagrant, you can just delete these files.
|
||||
TODO
|
||||
|
||||
|
||||
Django settings
|
||||
---------------
|
||||
|
||||
Location: ``/mysite/mysite/settings/``
|
||||
|
||||
The Django settings files are split up into ``base.py``, ``dev.py``, ``production.py`` and ``local.py``.
|
||||
|
||||
.. glossary::
|
||||
|
||||
``base.py``
|
||||
|
||||
This file is for global settings that will be used in both development and production. Aim to keep most of your configuration in this file.
|
||||
|
||||
``dev.py``
|
||||
|
||||
This file is for settings that will only be used by developers. For example: ``DEBUG = True``
|
||||
|
||||
``production.py``
|
||||
|
||||
This file is for settings that will only run on a production server. For example: ``DEBUG = False``
|
||||
|
||||
``local.py``
|
||||
|
||||
This file is used for settings local to a particular machine. This file should never be tracked by a version control system.
|
||||
|
||||
.. tip::
|
||||
|
||||
On production servers, we recommend that you only store secrets in local.py (such as API keys and passwords). This can save you headaches in the future if you are ever trying to debug why a server is behaving badly. If you are using multiple servers which need different settings then we recommend that you create a different ``production.py`` file for each one.
|
||||
|
||||
|
||||
Getting it running
|
||||
==================
|
||||
|
||||
|
||||
With Vagrant
|
||||
------------
|
||||
|
||||
This is the easiest way to get the project running. Vagrant runs your project locally in a virtual machine so you can use PostgreSQL and Elasticsearch in development without having to install them on your host machine. If you haven't yet installed Vagrant, see: `Installing Vagrant <https://docs.vagrantup.com/v2/installation/>`_.
|
||||
|
||||
|
||||
To setup the Vagrant box, run the following commands
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
vagrant up # This may take some time on first run
|
||||
vagrant ssh
|
||||
# within the ssh session
|
||||
dj createsuperuser
|
||||
djrun
|
||||
|
||||
|
||||
If you now visit http://localhost:8000 you should see a very basic "Welcome to your new Wagtail site!" page.
|
||||
|
||||
You can browse the Wagtail admin interface at: http://localhost:8000/admin
|
||||
|
||||
You can read more about how Vagrant works at: https://docs.vagrantup.com/v2/
|
||||
|
||||
|
||||
.. topic:: The ``dj`` and ``djrun`` aliases
|
||||
|
||||
When using Vagrant, the Wagtail template provides two aliases: ``dj`` and ``djrun`` which can be used in the ``vagrant ssh`` session.
|
||||
|
||||
.. glossary::
|
||||
|
||||
``dj``
|
||||
|
||||
This is short for ``python manage.py`` so you can use it to reduce typing. For example: ``python manage.py syncdb`` becomes ``dj syncdb``.
|
||||
|
||||
``djrun``
|
||||
|
||||
This is short for ``python manage.py runserver 0.0.0.0:8000``. This is used to run the testing server which is accessible from ``http://localhost:8000`` (note that the port number gets changed by Vagrant)
|
||||
:doc:`getting_started/using_vagrant`
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
|
||||
Before you start
|
||||
================
|
||||
|
||||
|
|
@ -10,75 +11,13 @@ A basic Wagtail setup can be installed on your machine with only a few prerequis
|
|||
Whether you just want to try out the demo site, or you're ready to dive in and create a Wagtail site with all bells and whistles enabled, we strongly recommend the Vagrant approach. Nevertheless, if you're the sort of person who balks at the idea of downloading a whole operating system just to run a web app, we've got you covered too. Start from `A basic Wagtail installation`_ below.
|
||||
|
||||
|
||||
The demo site (a.k.a. the no-installation route)
|
||||
================================================
|
||||
|
||||
We provide a demo site containing a set of standard templates and page types - if you're new to Wagtail, this is the best way to try it out and familiarise yourself with how Wagtail works from the point of view of an editor.
|
||||
|
||||
If you're happy to use Vagrant, and you just want to set up the Wagtail demo site, or any other pre-existing Wagtail site that ships with Vagrant support, you don't need to install Wagtail at all. Install `Vagrant <http://www.vagrantup.com/>`__ and `VirtualBox <https://www.virtualbox.org/>`__, and run::
|
||||
|
||||
git clone https://github.com/torchbox/wagtaildemo.git
|
||||
cd wagtaildemo
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
Install Python
|
||||
==============
|
||||
|
||||
|
||||
Then, within the SSH session::
|
||||
Install Wagtail
|
||||
===============
|
||||
|
||||
./manage.py createsuperuser
|
||||
./manage.py runserver 0.0.0.0:8000
|
||||
|
||||
|
||||
This will make the demo site available on your host machine at the URL http://localhost:8000/ - you can access the Wagtail admin interface at http://localhost:8000/admin/ . Further instructions can be found at :ref:`editor_manual`.
|
||||
|
||||
Once you’ve experimented with the demo site and are ready to build your own site, it's time to install Wagtail on your host machine. Even if you intend to do all further Wagtail work within Vagrant, installing the Wagtail package on your host machine will provide the ``wagtail start`` command that sets up the initial file structure for your project.
|
||||
|
||||
|
||||
A basic Wagtail installation
|
||||
============================
|
||||
|
||||
This provides everything you need to create a new Wagtail project from scratch, containing no page definitions or templates other than a basic homepage as a starting point for building your site. (For a gentler introduction to Wagtail, you may wish to try out the demo site first!)
|
||||
|
||||
You will need Python's `pip <http://pip.readthedocs.org/en/latest/installing.html>`__ package manager. We also recommend `virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ so that you can manage multiple independent Python environments for different projects - although this is not strictly necessary if you intend to do all your development under Vagrant.
|
||||
|
||||
Wagtail is based on the Django web framework and various other Python libraries. Most of these are pure Python and will install automatically using ``pip``, but there are a few native-code components that require further attention:
|
||||
|
||||
* libsass-python (for compiling SASS stylesheets) - requires a C++ compiler and the Python development headers.
|
||||
* Pillow (for image processing) - additionally requires libjpeg and zlib.
|
||||
|
||||
On Debian or Ubuntu, these can be installed with the command::
|
||||
|
||||
sudo apt-get install python-dev python-pip g++ libjpeg62-dev zlib1g-dev
|
||||
|
||||
With these dependencies installed, Wagtail can then be installed with the command::
|
||||
|
||||
pip install wagtail
|
||||
|
||||
(or if you're not using virtualenvwrapper: ``sudo pip install wagtail``.)
|
||||
|
||||
You will now be able to run the following command to set up an initial file structure for your Wagtail project (replace ``myprojectname`` with a name of your choice)::
|
||||
|
||||
wagtail start myprojectname
|
||||
|
||||
**Without Vagrant:** Run the following steps to complete setup of your project (the ``createsuperuser`` step will prompt you to set up a superuser account)::
|
||||
|
||||
cd myprojectname
|
||||
pip install -r requirements.txt
|
||||
python manage.py migrate
|
||||
python manage.py createsuperuser
|
||||
python manage.py runserver
|
||||
|
||||
Your site is now accessible at http://localhost:8000, with the admin backend available at http://localhost:8000/admin/ .
|
||||
|
||||
**With Vagrant:** Run the following steps to bring up the virtual machine and complete setup of your project (the ``createsuperuser`` step will prompt you to set up a superuser account)::
|
||||
|
||||
cd myprojectname
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
./manage.py createsuperuser
|
||||
./manage.py runserver 0.0.0.0:8000
|
||||
|
||||
Your site is now accessible at http://localhost:8000, with the admin backend available at http://localhost:8000/admin/ .
|
||||
|
||||
Optional extras
|
||||
===============
|
||||
|
|
@ -104,6 +43,7 @@ This assumes that your PostgreSQL instance is configured to allow you to connect
|
|||
|
||||
ElasticSearch
|
||||
-------------
|
||||
|
||||
Wagtail integrates with ElasticSearch to provide full-text searching of your content, both within the Wagtail interface and on your site's front-end. If ElasticSearch is not available, Wagtail will fall back to much more basic search functionality using database queries. ElasticSearch is pre-installed as part of the Vagrant virtual machine image; non-Vagrant users can use the `debian.sh <https://github.com/torchbox/wagtail/blob/master/scripts/install/debian.sh>`__ or `ubuntu.sh <https://github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh>`__ installation scripts as a guide.
|
||||
|
||||
To enable ElasticSearch for your project, uncomment the ``elasticsearch`` line from your project's requirements.txt, and in ``myprojectname/settings/base.py``, uncomment the WAGTAILSEARCH_BACKENDS section. Then run::
|
||||
|
|
@ -153,6 +93,7 @@ to your deployment preferences. The canonical version is at
|
|||
`github.com/torchbox/wagtail/blob/master/scripts/install/debian.sh
|
||||
<https://github.com/torchbox/wagtail/blob/master/scripts/install/debian.sh>`_.
|
||||
|
||||
|
||||
Docker
|
||||
------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,81 @@
|
|||
The project template
|
||||
====================
|
||||
|
||||
mysite/
|
||||
core/
|
||||
static/
|
||||
templates/
|
||||
base.html
|
||||
404.html
|
||||
500.html
|
||||
mysite/
|
||||
settings/
|
||||
base.py
|
||||
dev.py
|
||||
production.py
|
||||
manage.py
|
||||
vagrant/
|
||||
provision.sh
|
||||
Vagrantfile
|
||||
readme.rst
|
||||
requirements.txt
|
||||
|
||||
|
||||
The "core" app
|
||||
----------------
|
||||
|
||||
Location: ``/mysite/core/``
|
||||
|
||||
This app is here to help get you started quicker by providing a ``HomePage`` model with migrations to create one when you first setup your app.
|
||||
|
||||
|
||||
Default templates and static files
|
||||
----------------------------------
|
||||
|
||||
Location: ``/mysite/core/templates/`` and ``/mysite/core/static/``
|
||||
|
||||
The templates directory contains ``base.html``, ``404.html`` and ``500.html``. These files are very commonly needed on Wagtail sites to they have been added into the template.
|
||||
|
||||
The static directory contains an empty javascript and sass file. Wagtail uses ``django-compressor`` for compiling and compressing static files. For more information, see: `Django Compressor Documentation <http://django-compressor.readthedocs.org/en/latest/>`_
|
||||
|
||||
|
||||
Vagrant configuration
|
||||
---------------------
|
||||
|
||||
Location: ``/Vagrantfile`` and ``/vagrant/``
|
||||
|
||||
If you have Vagrant installed, these files let you easily setup a development environment with PostgreSQL and Elasticsearch inside a virtual machine.
|
||||
|
||||
See below section `With Vagrant`_ for info on how to use Vagrant in development
|
||||
|
||||
If you do not want to use Vagrant, you can just delete these files.
|
||||
|
||||
|
||||
Django settings
|
||||
---------------
|
||||
|
||||
Location: ``/mysite/mysite/settings/``
|
||||
|
||||
The Django settings files are split up into ``base.py``, ``dev.py``, ``production.py`` and ``local.py``.
|
||||
|
||||
.. glossary::
|
||||
|
||||
``base.py``
|
||||
|
||||
This file is for global settings that will be used in both development and production. Aim to keep most of your configuration in this file.
|
||||
|
||||
``dev.py``
|
||||
|
||||
This file is for settings that will only be used by developers. For example: ``DEBUG = True``
|
||||
|
||||
``production.py``
|
||||
|
||||
This file is for settings that will only run on a production server. For example: ``DEBUG = False``
|
||||
|
||||
``local.py``
|
||||
|
||||
This file is used for settings local to a particular machine. This file should never be tracked by a version control system.
|
||||
|
||||
.. tip::
|
||||
|
||||
On production servers, we recommend that you only store secrets in local.py (such as API keys and passwords). This can save you headaches in the future if you are ever trying to debug why a server is behaving badly. If you are using multiple servers which need different settings then we recommend that you create a different ``production.py`` file for each one.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
Using Vagrant
|
||||
=============
|
||||
|
||||
This is the easiest way to get the project running. Vagrant runs your project locally in a virtual machine so you can use PostgreSQL and Elasticsearch in development without having to install them on your host machine. If you haven't yet installed Vagrant, see: `Installing Vagrant <https://docs.vagrantup.com/v2/installation/>`_.
|
||||
|
||||
|
||||
To setup the Vagrant box, run the following commands
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
vagrant up # This may take some time on first run
|
||||
vagrant ssh
|
||||
# within the ssh session
|
||||
dj createsuperuser
|
||||
djrun
|
||||
|
||||
|
||||
If you now visit http://localhost:8111 you should see a very basic "Welcome to your new Wagtail site!" page.
|
||||
|
||||
You can browse the Wagtail admin interface at: http://localhost:8111/admin
|
||||
|
||||
You can read more about how Vagrant works at: https://docs.vagrantup.com/v2/
|
||||
|
||||
|
||||
.. topic:: The ``dj`` and ``djrun`` aliases
|
||||
|
||||
When using Vagrant, the Wagtail template provides two aliases: ``dj`` and ``djrun`` which can be used in the ``vagrant ssh`` session.
|
||||
|
||||
.. glossary::
|
||||
|
||||
``dj``
|
||||
|
||||
This is short for ``python manage.py`` so you can use it to reduce typing. For example: ``python manage.py syncdb`` becomes ``dj syncdb``.
|
||||
|
||||
``djrun``
|
||||
|
||||
This is short for ``python manage.py runserver 0.0.0.0:8000``. This is used to run the testing server which is accessible from ``http://localhost:8111`` (note that the port number gets changed by Vagrant)
|
||||
Ładowanie…
Reference in New Issue