kopia lustrzana https://github.com/wagtail/wagtail
Simplified getting started section
Dave Cranwell
Karl Hobley
rodzic
ca0085c68d
commit
bd45a12efd
|
|
@ -1,76 +0,0 @@
|
|||
===========================
|
||||
Starting your first project
|
||||
===========================
|
||||
|
||||
Once you've installed Wagtail, you are ready start your first project. Wagtail projects are ordinary Django projects with a few extra apps installed.
|
||||
|
||||
Wagtail provides a command to get you started called ``wagtail start``. Open up a command line shell in your project folder and type:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wagtail start mysite
|
||||
|
||||
|
||||
This should create a new folder called ``mysite``. Its contents are similar to what ``django-admin.py startproject`` creates but ``wagtail start`` comes with some useful extras that are documented :doc:`here <../reference/project_template>`.
|
||||
|
||||
|
||||
Running it
|
||||
==========
|
||||
|
||||
Firstly, open up a command line shell in your new projects directory.
|
||||
|
||||
|
||||
1. **Create a virtual environment**
|
||||
|
||||
This is only required when you first run your project. This creates a folder to install extra Python modules into.
|
||||
|
||||
**Linux/Mac OSX:** :code:`pyvenv venv`
|
||||
|
||||
**Windows:** :code:`c:\Python34\python -m venv myenv`
|
||||
|
||||
|
||||
https://docs.python.org/3/library/venv.html
|
||||
|
||||
|
||||
**Python 2.7**
|
||||
|
||||
``pyvenv`` is only included with Python 3.3 onwards. To get virtual environments on Python 2, use the ``virtualenv`` package:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install virtualenv
|
||||
virtualenv venv
|
||||
|
||||
2. **Activate the virtual environment**
|
||||
|
||||
**Linux/Mac OSX:** :code:`source venv/bin/activate`
|
||||
|
||||
**Windows:** :code:`venv/Scripts/activate.bat`
|
||||
|
||||
https://docs.python.org/3/library/venv.html
|
||||
|
||||
3. **Install PIP requirements**
|
||||
|
||||
:code:`pip install -r requirements.txt`
|
||||
|
||||
4. **Create the database**
|
||||
|
||||
By default, this would create an SQLite database file within the project directory.
|
||||
|
||||
:code:`python manage.py migrate`
|
||||
|
||||
5. **Create an admin user**
|
||||
|
||||
:code:`python manage.py createsuperuser`
|
||||
|
||||
6. **Run the development server**
|
||||
|
||||
:code:`python manage.py runserver`
|
||||
|
||||
Your site is now accessible at ``http://localhost:8000``, with the admin backend available at ``http://localhost:8000/admin/``.
|
||||
|
||||
|
||||
Using Vagrant
|
||||
-------------
|
||||
|
||||
:doc:`using_vagrant`
|
||||
|
|
@ -3,6 +3,6 @@ Demo site
|
|||
=========
|
||||
|
||||
|
||||
To create a new site on Wagtail we recommend the ``wagtail start`` command in :doc:`creating_your_project`, however a demo site exists containing example page types and models. We also recommend you use the demo site for testing during development of Wagtail itself.
|
||||
To create a new site on Wagtail we recommend the ``wagtail start`` command in :doc:`index`, however a demo site exists containing example page types and models. We also recommend you use the demo site for testing during development of Wagtail itself.
|
||||
|
||||
The repo and installation instructions can be found here: `https://github.com/torchbox/wagtaildemo <https://github.com/torchbox/wagtaildemo>`_
|
||||
|
|
|
|||
|
|
@ -1,11 +1,46 @@
|
|||
Getting started
|
||||
===============
|
||||
|
||||
Wagtail is built on the `Django web framework <https://www.djangoproject.com/>`_, so this document assumes you've already got the essentials installed. But if not, those essentials are:
|
||||
|
||||
* `Python <https://www.python.org/downloads/>`_
|
||||
* `pip <https://pip.pypa.io/en/latest/installing.html>`_ (Note that pip is included by default with Python 2.7.9 and later and Python 3.4 and later)
|
||||
|
||||
We'd also recommend Virtualenv, which provides isolated Python environments:
|
||||
|
||||
* `Virtualenv <https://virtualenv.pypa.io/en/latest/installation.html>`_
|
||||
|
||||
|
||||
Before we install Wagtail we should install Pillow for image manipulation. Before you run ``pip install Pillow`` note that most platforms require you install additional libraries first: `Platform-specific installation instructions <http://pillow.readthedocs.org/en/latest/installation.html#os-x-installation>`_
|
||||
|
||||
With the above installed, the quickest way to install Wagtail is::
|
||||
|
||||
pip install wagtail
|
||||
|
||||
(``sudo`` may be required if installing system-wide or without virtualenv)
|
||||
|
||||
Once installed, Wagtail provides a command similar to Django's ``django-admin startproject`` which stubs out a new site/project::
|
||||
|
||||
wagtail start mysite
|
||||
|
||||
This will create a new folder ``mysite``, based on a template containing all you need to get started. More information on that template is available :doc:`here </reference/project_template>`.
|
||||
|
||||
Inside your ``mysite`` folder, we now just run the setup steps necessary for any Django project::
|
||||
|
||||
./manage.py migrate
|
||||
./manage.py createsuperuser
|
||||
./manage.py runserver
|
||||
|
||||
Your site is now accessible at ``http://localhost:8000``, with the admin backend available at ``http://localhost:8000/admin/``.
|
||||
|
||||
|
||||
There are a few optional packages which are not installed by default but are recommended to improve performance or add features to Wagtail, including:
|
||||
|
||||
* :doc:`Elasticsearch </howto/performance>`.
|
||||
* :ref:`image_feature_detection`.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
creating_your_project
|
||||
using_vagrant
|
||||
demo_site
|
||||
|
|
|
|||
|
|
@ -1,107 +0,0 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
|
||||
Before you start
|
||||
================
|
||||
|
||||
You can get basic Wagtail setup installed on your machine with only a few prerequisites. See the full `Dependencies`_ list below.
|
||||
|
||||
There are various optional components that will improve the performance and feature set of Wagtail. Our recommended software stack includes the PostgreSQL database, Elasticsearch (for free-text searching), the OpenCV library (for image feature detection), and Redis (as a cache and message queue backend). This would be a lot to install in one go. For this reason we provide a virtual machine image to use with `Vagrant <http://www.vagrantup.com/>`__, with all of these components ready installed.
|
||||
|
||||
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 `Install Python`_.
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Wagtail is based on the Django web framework and various other Python libraries. For the full list of absolutely required libraries, see `setup.py <https://github.com/torchbox/wagtail/blob/master/setup.py>`__.
|
||||
|
||||
Most of Wagtail's dependencies are pure Python and will install automatically using ``pip``, but there are a few native-code components that require further attention:
|
||||
|
||||
* 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
|
||||
|
||||
Install Python
|
||||
==============
|
||||
|
||||
If you haven't got Python installed yet, we recommend installing Python 3.4. You can download it here: https://www.python.org/downloads/
|
||||
|
||||
|
||||
pip
|
||||
---
|
||||
|
||||
Python 3.4 has this built in. If you are using Python 2.7 or 3.3, you will have to install PIP separately
|
||||
|
||||
See: https://pip.pypa.io/en/latest/installing.html
|
||||
|
||||
|
||||
Virtual environments
|
||||
--------------------
|
||||
|
||||
Python 3.3 and 3.4 has this built in. If you are using Python 2.7 you can install the ``virtualenv`` package using pip:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install virtualenv
|
||||
|
||||
|
||||
Install Wagtail
|
||||
===============
|
||||
|
||||
The quickest way to install Wagtail is using pip. To get the latest stable version:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install wagtail
|
||||
|
||||
|
||||
If you are installing Wagtail differently (e.g. from the Git repository), you must run ``python setup.py install`` from the repository root. The above command will install all Wagtail dependencies.
|
||||
|
||||
To check that Wagtail can be seen by Python, type ``python`` in your shell then try to import ``wagtail`` from the prompt:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> import wagtail
|
||||
|
||||
|
||||
Optional extras
|
||||
===============
|
||||
|
||||
For the best possible performance and feature set, we recommend setting up the following components. If you're using Vagrant, these are provided as part of the virtual machine image and just need to be enabled in the settings for your project. If you're using Wagtail without Vagrant, this will involve additional installation.
|
||||
|
||||
|
||||
PostgreSQL
|
||||
----------
|
||||
PostgreSQL is a mature database engine suitable for production use, and is recommended by the Django development team. Non-Vagrant users will need to install the PostgreSQL development headers in addition to PostgreSQL itself; on Debian or Ubuntu, this can be done with the following command::
|
||||
|
||||
sudo apt-get install postgresql postgresql-server-dev-all
|
||||
|
||||
To enable PostgreSQL for your project, uncomment the ``psycopg2`` line from your project's requirements.txt, and in ``myprojectname/settings/base.py``, uncomment the DATABASES section for PostgreSQL, commenting out the SQLite one instead. Then run::
|
||||
|
||||
pip install -r requirements.txt
|
||||
createdb -Upostgres myprojectname
|
||||
./manage.py migrate
|
||||
./manage.py createsuperuser
|
||||
|
||||
This assumes that your PostgreSQL instance is configured to allow you to connect as the 'postgres' user - if not, you'll need to adjust the ``createdb`` line and the database settings in settings/base.py accordingly.
|
||||
|
||||
|
||||
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::
|
||||
|
||||
pip install -r requirements.txt
|
||||
./manage.py update_index
|
||||
|
||||
|
||||
Image feature detection
|
||||
-----------------------
|
||||
Wagtail can use the OpenCV computer vision library to detect faces and other features in images, and use this information to select the most appropriate centre point when cropping the image. OpenCV is pre-installed as part of the Vagrant virtual machine image, and Vagrant users can enable this by setting ``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED`` to True in ``myprojectname/settings/base.py``. For installation outside of Vagrant, see :ref:`image_feature_detection`.
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
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: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)
|
||||
|
|
@ -33,6 +33,23 @@ Search
|
|||
|
||||
Wagtail has strong support for `Elasticsearch <http://www.elasticsearch.org/>`_ - both in the editor interface and for users of your site - but can fall back to a database search if Elasticsearch isn't present. Elasticsearch is faster and more powerful than the Django ORM for text search, so we recommend installing it or using a hosted service like `Searchly <http://www.searchly.com/>`_.
|
||||
|
||||
Once the Elasticsearch server is installed and running. Install the ``elasticsearch`` Python module with::
|
||||
|
||||
pip install elasticsearch
|
||||
|
||||
then add the following to your settings::
|
||||
|
||||
WAGTAILSEARCH_BACKENDS = {
|
||||
'default': {
|
||||
'BACKEND': 'wagtail.wagtailsearch.backends.elasticsearch.ElasticSearch',
|
||||
'INDEX': '{{ project_name }}',
|
||||
},
|
||||
}
|
||||
|
||||
Once Elasticsearch is configured, you can index any existing content you may have::
|
||||
|
||||
./manage.py update_index
|
||||
|
||||
|
||||
Database
|
||||
--------
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ Middleware (``settings.py``)
|
|||
Wagtail requires several common Django middleware modules to work and cover basic security. Wagtail provides its own middleware to cover these tasks:
|
||||
|
||||
``SiteMiddleware``
|
||||
Wagtail routes pre-defined hosts to pages within the Wagtail tree using this middleware. For configuring sites, see :ref:`wagtail_site_admin`.
|
||||
Wagtail routes pre-defined hosts to pages within the Wagtail tree using this middleware.
|
||||
|
||||
``RedirectMiddleware``
|
||||
Wagtail provides a simple interface for adding arbitrary redirects to your site and this module makes it happen.
|
||||
|
|
|
|||
|
|
@ -8,10 +8,8 @@ Below are some useful links to help you get started with Wagtail.
|
|||
|
||||
* **First steps**
|
||||
|
||||
* :doc:`getting_started/index`
|
||||
* :doc:`getting_started/demo_site`
|
||||
* :doc:`getting_started/installation`
|
||||
* :doc:`getting_started/creating_your_project`
|
||||
|
||||
|
||||
* **Creating your Wagtail site**
|
||||
|
||||
|
|
|
|||
|
|
@ -48,8 +48,6 @@ 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 :doc:`../getting_started/using_vagrant` for info on how to use Vagrant in development
|
||||
|
||||
If you do not want to use Vagrant, you can just delete these files.
|
||||
|
||||
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue