kopia lustrzana https://github.com/wagtail/wagtail
New installation docs
Matt Westcott
rodzic
446fd81a46
commit
c442ddefde
|
|
@ -4,50 +4,160 @@
|
|||
Getting started
|
||||
===============
|
||||
|
||||
Installing Wagtail
|
||||
==================
|
||||
Before you start
|
||||
================
|
||||
|
||||
From PyPI
|
||||
---------
|
||||
A basic Wagtail setup can be installed on your machine with only a few prerequisites - see `A basic Wagtail installation`_. However, there are various optional components that will improve the performance and feature set of Wagtail, and 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, and for this reason, we provide a virtual machine image, for use with `Vagrant <http://www.vagrantup.com/>`__, with all of these components ready installed.
|
||||
|
||||
This is recommended for stability.
|
||||
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.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
The no-installation route
|
||||
=========================
|
||||
|
||||
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
|
||||
|
||||
|
||||
Then, within the SSH session::
|
||||
|
||||
./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:8111/ - you can access the Wagtail admin interface at http://localhost:8111/admin/ .
|
||||
|
||||
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
|
||||
============================
|
||||
|
||||
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``.)
|
||||
|
||||
From Github
|
||||
-----------
|
||||
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)::
|
||||
|
||||
This will give you the latest development version of Wagtail.
|
||||
wagtail start myprojectname
|
||||
|
||||
.. code-block:: bash
|
||||
**Without Vagrant:** Run the following steps to complete setup of your project (the ``migrate`` step will prompt you to set up a superuser account)::
|
||||
|
||||
pip install -e git://github.com/torchbox/wagtail.git#egg=wagtail
|
||||
cd myprojectname
|
||||
./manage.py syncdb
|
||||
./manage.py migrate
|
||||
./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:8111, with the admin backend available at http://localhost:8111/admin/ .
|
||||
|
||||
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.
|
||||
|
||||
|
||||
The ``wagtail`` command
|
||||
=======================
|
||||
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 Postgres itself; on Debian or Ubuntu, this can be done with the following command::
|
||||
|
||||
.. versionadded:: 0.5
|
||||
sudo apt-get install postgresql postgresql-server-dev-all
|
||||
|
||||
Once you have Wagtail installed on your host machine, you can use the ``wagtail`` command.
|
||||
To enable Postgres 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::
|
||||
|
||||
Usage:
|
||||
pip install -r requirements.txt
|
||||
createdb -Upostgres myprojectname
|
||||
./manage.py syncdb
|
||||
./manage.py migrate
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wagtail start <project name>
|
||||
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.
|
||||
|
||||
|
||||
This command will setup a skeleton Wagtail project with the following features installed:
|
||||
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.
|
||||
|
||||
- A core app with migrations to replace the default Homepage
|
||||
- Base templates (base, 404, 500)
|
||||
- Vagrant configuration
|
||||
- Fabfile
|
||||
- Docs directory (with Sphinx configuration)
|
||||
- Split up settings configuration (different settings for dev and production)
|
||||
- Requirements
|
||||
|
||||
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. See :ref:`image_feature_detection` for details on setting this up.
|
||||
|
||||
|
||||
Alternative installation methods
|
||||
================================
|
||||
|
||||
Ubuntu
|
||||
------
|
||||
|
||||
If you have a fresh instance of Ubuntu 13.04 or later, you can install Wagtail,
|
||||
along with a demonstration site containing a set of standard templates and page
|
||||
types, in one step. As the root user::
|
||||
|
||||
curl -O https://wagtail.io/ubuntu.sh; bash ubuntu.sh
|
||||
|
||||
This script installs all the dependencies for a production-ready Wagtail site,
|
||||
including PostgreSQL, Redis, Elasticsearch, Nginx and uwsgi. We
|
||||
recommend you check through the script before running it, and adapt it according
|
||||
to your deployment preferences. The canonical version is at
|
||||
`github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh
|
||||
<https://github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh>`_.
|
||||
|
||||
|
||||
Debian
|
||||
------
|
||||
|
||||
If you have a fresh instance of Debian 7, you can install Wagtail, along with a
|
||||
demonstration site containing a set of standard templates and page types, in one
|
||||
step. As the root user::
|
||||
|
||||
curl -O https://wagtail.io/debian.sh; bash debian.sh
|
||||
|
||||
This script installs all the dependencies for a production-ready Wagtail site,
|
||||
including PostgreSQL, Redis, Elasticsearch, Nginx and uwsgi. We
|
||||
recommend you check through the script before running it, and adapt it according
|
||||
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
|
||||
------
|
||||
|
||||
`@oyvindsk <https://github.com/oyvindsk>`_ has built a Dockerfile for the Wagtail demo. Simply run::
|
||||
|
||||
docker run -p 8000:8000 -d oyvindsk/wagtail-demo
|
||||
|
||||
then access the site at http://your-ip:8000 and the admin
|
||||
interface at http://your-ip:8000/admin using admin / test.
|
||||
|
||||
See https://index.docker.io/u/oyvindsk/wagtail-demo/ for more details.
|
||||
|
|
|
|||
|
|
@ -8,9 +8,7 @@ It supports Django 1.6.2+ and 1.7rc3+ on Python 2.6, 2.7, 3.2, 3.3 and 3.4.
|
|||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
trying_the_demo
|
||||
getting_started
|
||||
gettingstarted
|
||||
core_components/index
|
||||
contrib_components/index
|
||||
howto/index
|
||||
|
|
|
|||
|
|
@ -1,156 +0,0 @@
|
|||
Trying the demo
|
||||
---------------
|
||||
|
||||
On Ubuntu
|
||||
~~~~~~~~~
|
||||
|
||||
If you have a fresh instance of Ubuntu 13.04 or later, you can install Wagtail,
|
||||
along with a demonstration site containing a set of standard templates and page
|
||||
types, in one step. As the root user::
|
||||
|
||||
curl -O https://wagtail.io/ubuntu.sh; bash ubuntu.sh
|
||||
|
||||
This script installs all the dependencies for a production-ready Wagtail site,
|
||||
including PostgreSQL, Redis, Elasticsearch, Nginx and uwsgi. We
|
||||
recommend you check through the script before running it, and adapt it according
|
||||
to your deployment preferences. The canonical version is at
|
||||
`github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh
|
||||
<https://github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh>`_.
|
||||
|
||||
|
||||
On Debian
|
||||
~~~~~~~~~
|
||||
|
||||
If you have a fresh instance of Debian 7, you can install Wagtail, along with a
|
||||
demonstration site containing a set of standard templates and page types, in one
|
||||
step. As the root user::
|
||||
|
||||
curl -O https://wagtail.io/debian.sh; bash debian.sh
|
||||
|
||||
This script installs all the dependencies for a production-ready Wagtail site,
|
||||
including PostgreSQL, Redis, Elasticsearch, Nginx and uwsgi. We
|
||||
recommend you check through the script before running it, and adapt it according
|
||||
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>`_.
|
||||
|
||||
|
||||
On OS X
|
||||
~~~~~~~
|
||||
|
||||
Install `pip <http://pip.readthedocs.org/en/latest/installing.html>`__ and `virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ if you don't have them already. Then, in your terminal::
|
||||
|
||||
mkvirtualenv wagtaildemo
|
||||
git clone https://github.com/torchbox/wagtaildemo.git
|
||||
cd wagtaildemo
|
||||
pip install -r requirements/dev.txt
|
||||
|
||||
Edit ``wagtaildemo/settings/base.py``, changing ENGINE to django.db.backends.sqlite3 and NAME to wagtail.db. Finally, setup the database and run the local server::
|
||||
|
||||
./manage.py syncdb
|
||||
./manage.py migrate
|
||||
./manage.py runserver
|
||||
|
||||
|
||||
Using Vagrant
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
We provide a Vagrant box which includes all the dependencies for a fully-fledged
|
||||
Wagtail environment, bundled with a demonstration site containing a set of
|
||||
standard templates and page types. If you have a good internet connection we recommend
|
||||
the following steps, which will download the 650MB Vagrant box and make a running
|
||||
Wagtail instance available as the basis for your new site:
|
||||
|
||||
- Install `Vagrant <http://www.vagrantup.com/>`_ 1.1+
|
||||
- Clone the demonstration site, create the Vagrant box and initialise Wagtail::
|
||||
|
||||
git clone https://github.com/torchbox/wagtaildemo.git
|
||||
cd wagtaildemo
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
# within the SSH session
|
||||
./manage.py createsuperuser
|
||||
./manage.py update_index
|
||||
./manage.py runserver 0.0.0.0:8000
|
||||
|
||||
- This will make the app accessible on the host machine as
|
||||
`localhost:8111 <http://localhost:8111>`_ - you can access the Wagtail admin
|
||||
interface at `localhost:8111/admin <http://localhost:8111/admin>`_. The codebase
|
||||
is located on the host machine, exported to the VM as a shared folder; code
|
||||
editing and Git operations will generally be done on the host.
|
||||
|
||||
|
||||
Using Docker
|
||||
~~~~~~~~~~~~
|
||||
|
||||
`@oyvindsk <https://github.com/oyvindsk>`_ has built a Dockerfile for the Wagtail demo. Simply run::
|
||||
|
||||
docker run -p 8000:8000 -d oyvindsk/wagtail-demo
|
||||
|
||||
then access the site at http://your-ip:8000 and the admin
|
||||
interface at http://your-ip:8000/admin using admin / test.
|
||||
|
||||
See https://index.docker.io/u/oyvindsk/wagtail-demo/ for more details.
|
||||
|
||||
|
||||
Other platforms
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
If you're not using Ubuntu or Debian, or if you prefer to install Wagtail manually,
|
||||
use the following steps:
|
||||
|
||||
|
||||
Required dependencies
|
||||
=====================
|
||||
|
||||
- `pip <https://github.com/pypa/pip>`__
|
||||
- `libjpeg <http://ijg.org/>`_
|
||||
- `libxml2 <http://xmlsoft.org/>`_
|
||||
- `libxslt <http://xmlsoft.org/XSLT/>`_
|
||||
- `zlib <http://www.zlib.net/>`_
|
||||
|
||||
|
||||
Optional dependencies
|
||||
=====================
|
||||
|
||||
- `PostgreSQL`_
|
||||
- `Elasticsearch`_
|
||||
- `Redis`_
|
||||
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
With PostgreSQL running (and 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 wagtaildemo/settings/base.py accordingly),
|
||||
run the following commands::
|
||||
|
||||
git clone https://github.com/torchbox/wagtaildemo.git
|
||||
cd wagtaildemo
|
||||
pip install -r requirements/dev.txt
|
||||
createdb -Upostgres wagtaildemo
|
||||
./manage.py syncdb
|
||||
./manage.py migrate
|
||||
./manage.py runserver
|
||||
|
||||
|
||||
SQLite support
|
||||
==============
|
||||
|
||||
SQLite is supported as an alternative to PostgreSQL - update the DATABASES setting
|
||||
in wagtaildemo/settings/base.py to use 'django.db.backends.sqlite3', as you would
|
||||
with a regular Django project.
|
||||
|
||||
.. _Wagtail: http://wagtail.io
|
||||
.. _VirtualBox: https://www.virtualbox.org/
|
||||
.. _the Wagtail codebase: https://github.com/torchbox/wagtail
|
||||
.. _PostgreSQL: http://www.postgresql.org
|
||||
.. _Elasticsearch: http://www.elasticsearch.org
|
||||
.. _Redis: http://redis.io/
|
||||
|
||||
|
||||
Creating your own site
|
||||
======================
|
||||
|
||||
Once you've experimented with the demo app and are ready to build your pages via your own app take a look at the :ref:`getting_started` documentation.
|
||||
Ładowanie…
Reference in New Issue