allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kentontay...@apache.org
Subject [6/6] allura git commit: [#7908] split step-by-step instructions to separate doc; Add note to docker setup about using production files
Date Mon, 30 Oct 2017 14:43:01 GMT
[#7908] split step-by-step instructions to separate doc; Add note to docker setup about using
production files


Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/53b18cd8
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/53b18cd8
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/53b18cd8

Branch: refs/heads/master
Commit: 53b18cd86b59700257276f2a91704c87a2c4aa07
Parents: 9a35a13
Author: Dave Brondsema <dave@brondsema.net>
Authored: Fri Sep 29 13:40:17 2017 -0400
Committer: Kenton Taylor <ktaylor@slashdotmedia.com>
Committed: Mon Oct 30 10:42:33 2017 -0400

----------------------------------------------------------------------
 Allura/docs/getting_started/index.rst           |   1 +
 .../docs/getting_started/install_each_step.rst  | 239 +++++++++++++++++++
 Allura/docs/getting_started/installation.rst    | 224 +----------------
 README.markdown                                 |   4 +-
 4 files changed, 250 insertions(+), 218 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/allura/blob/53b18cd8/Allura/docs/getting_started/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/index.rst b/Allura/docs/getting_started/index.rst
index 6f59b58..f2c8a2c 100644
--- a/Allura/docs/getting_started/index.rst
+++ b/Allura/docs/getting_started/index.rst
@@ -25,6 +25,7 @@ Getting Started
 
     about
     installation
+    install_each_step
     using
     administration
     scm_host

http://git-wip-us.apache.org/repos/asf/allura/blob/53b18cd8/Allura/docs/getting_started/install_each_step.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/install_each_step.rst b/Allura/docs/getting_started/install_each_step.rst
new file mode 100644
index 0000000..42f4a9b
--- /dev/null
+++ b/Allura/docs/getting_started/install_each_step.rst
@@ -0,0 +1,239 @@
+..     Licensed to the Apache Software Foundation (ASF) under one
+       or more contributor license agreements.  See the NOTICE file
+       distributed with this work for additional information
+       regarding copyright ownership.  The ASF licenses this file
+       to you under the Apache License, Version 2.0 (the
+       "License"); you may not use this file except in compliance
+       with the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing,
+       software distributed under the License is distributed on an
+       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+       KIND, either express or implied.  See the License for the
+       specific language governing permissions and limitations
+       under the License.
+
+.. _step-by-step-install:
+
+*************************
+Step-by-Step Installation
+*************************
+
+.. contents::
+   :local:
+
+Step-by-Step Installation
+-------------------------
+
+For a simpler setup using Docker images, see :ref:`docker-install` instead.
+
+In these instructions, we'll use `VirtualBox <http://www.virtualbox.org>`__ and `Ubuntu
16.04 <http://ubuntu.com>`_ (15.04 works too) to create a disposable sandbox for Allura
development/testing.  Allura should work on other Linux systems (including OSX), but setting
up all the dependencies will be different.
+
+* Download and install `VirtualBox <http://www.virtualbox.org/wiki/Downloads>`__ for
your platform.
+
+* Download a minimal `Ubuntu 16.04 64-bit ISO <https://help.ubuntu.com/community/Installation/MinimalCD>`_.
+
+* Create a new virtual machine in Virtual Box, selecting Ubuntu (64 bit) as the OS type.
 The rest of the wizards' defaults are fine.
+
+* When you launch the virtual machine for the first time, you will be prompted to attach
your installation media.  Browse to the :file:`mini.iso` that you downloaded earlier.
+
+* After a text-only installation, you may end up with a blank screen and blinking cursor.
 Press :code:`Alt-F1` to switch to the first console.
+
+* Consult `available documentation <https://help.ubuntu.com/>`_ for help installing
Ubuntu.
+
+
+System Packages
+^^^^^^^^^^^^^^^
+
+Before we begin, you'll need to install some system packages.
+
+.. code-block:: bash
+
+    ~$ sudo apt-get install git-core python2.7-dev libssl-dev libldap2-dev libsasl2-dev libjpeg8-dev
zlib1g-dev libffi-dev
+
+To install MongoDB, follow the instructions `here <https://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/>`_.
+
+Optional, for SVN support:
+
+.. code-block:: bash
+
+    ~$ sudo apt-get install subversion python-svn
+
+Setting up a virtual python environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first step to installing the Allura platform is installing a virtual environment via
`virtualenv <https://virtualenv.pypa.io/en/latest/>`_.  This helps keep our distribution
python installation clean.
+
+.. code-block:: bash
+
+    ~$ sudo apt-get install python-pip
+    ~$ sudo pip install virtualenv
+
+Once you have virtualenv installed, you need to create a virtual environment.  We'll call
our Allura environment 'env-allura'.
+
+.. code-block:: bash
+
+    ~$ virtualenv env-allura
+
+This gives us a nice, clean environment into which we can install all the allura dependencies.
+In order to use the virtual environment, you'll need to activate it:
+
+.. code-block:: bash
+
+    ~$ . env-allura/bin/activate
+
+You'll need to do this whenever you're working on the Allura codebase so you may want to
consider adding it to your :file:`~/.bashrc` file.
+
+Creating the log directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    (env-allura)~$ sudo mkdir -p /var/log/allura
+    (env-allura)~$ sudo chown $(whoami) /var/log/allura
+
+Installing the Allura code and dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now we can get down to actually getting the Allura code and dependencies downloaded and ready
to go.  If you don't have the source code yet, run:
+
+.. code-block:: bash
+
+    (env-allura)~$ mkdir src
+    (env-allura)~$ cd src
+    (env-allura)~/src$ git clone https://git-wip-us.apache.org/repos/asf/allura.git allura
+
+If you already reading this file from an Allura release or checkout, you're ready to continue.
+
+Although the application :file:`setup.py` files define a number of dependencies, the :file:`requirements.txt`
files are currently the authoritative source, so we'll use those with `pip <https://pip.pypa.io/en/stable/>`_
to make sure the correct versions are installed.
+
+.. code-block:: bash
+
+    (env-allura)~/src$ cd allura
+    (env-allura)~/src/allura$ pip install -r requirements.txt
+
+This will take a while.  If you get an error from pip, it is typically a temporary download
error.  Just run the command again and it will quickly pass through the packages it already
downloaded and then continue.
+
+Optional, for SVN support: symlink the system pysvn package into our virtual environment
+
+.. code-block:: bash
+
+    (env-allura)~/src/allura$ ln -s /usr/lib/python2.7/dist-packages/pysvn ~/env-allura/lib/python2.7/site-packages/
+
+Next, run this to set up all the Allura tools:
+
+.. code-block:: bash
+
+    (env-allura)~/src/allura$ ./rebuild-all.bash
+
+.. note::
+
+    If you only want to use a few tools, run this instead:
+
+    .. code-block:: bash
+
+        (env-allura)~/src/allura$ cd Allura
+        (env-allura)~/src/allura/Allura$ python setup.py develop
+        (env-allura)~/src/allura/Allura$ cd ../ForgeWiki   # required tool
+        (env-allura)~/src/allura/ForgeWiki$ python setup.py develop
+        # repeat for any other tools you want to use
+
+Initializing the environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Allura forge consists of several components, all of which need to be running to have
full functionality.
+
+SOLR search and indexing server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We have a custom config ready for use.
+
+.. code-block:: bash
+
+    (env-allura)~$ cd tmp
+    (env-allura)/tmp$ sudo apt-get install default-jre-headless unzip
+    (env-allura)/tmp$ wget -nv http://archive.apache.org/dist/lucene/solr/5.3.1/solr-5.3.1.tgz
+    (env-allura)/tmp$ tar xvf solr-5.3.1.tgz solr-5.3.1/bin/install_solr_service.sh --strip-components=2
+    (env-allura)/tmp$ sudo ./install_solr_service.sh solr-5.3.1.tgz
+
+    (env-allura)/tmp$ cd ~/src/allura
+    (env-allura)~/src/allura$ sudo -H -u solr bash -c 'cp -R solr_config/allura/ /var/solr/data/'
+    (env-allura)~/src/allura$ sudo service solr start
+
+
+Create code repo directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default configuration stores repos in :file:`/srv`, so we need to create those directories:
+
+.. code-block:: bash
+
+    ~$ sudo mkdir /srv/{git,svn,hg}
+    ~$ sudo chown $USER /srv/{git,svn,hg}
+    ~$ sudo chmod 775 /srv/{git,svn,hg}
+
+If you don't have :code:`sudo` permission or just want to store them somewhere else, change
the :file:`/srv` paths in :file:`development.ini`
+
+If you want to set up remote access to the repositories, see :ref:`scm_hosting`
+
+Allura task processing
+~~~~~~~~~~~~~~~~~~~~~~
+
+Allura uses a background task service called "taskd" to do async tasks like sending emails,
and indexing data into solr, etc.  Let's get it running
+
+.. code-block:: bash
+
+    (env-allura)~$ cd ~/src/allura/Allura
+    (env-allura)~/src/allura/Allura$ nohup paster taskd development.ini > /var/log/allura/taskd.log
2>&1 &
+
+
+A few more steps, if using git
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using a released version of Allura, these are already done for you.  This transpiles
JS into a version all browsers support.
+For non-Ubuntu installations see https://nodejs.org/en/download/package-manager/ for other
options to replace the first line here:
+
+.. code-block:: bash
+
+    (env-allura)~$ curl --silent --location https://deb.nodesource.com/setup_4.x | sudo bash
-
+    (env-allura)~$ sudo apt-get install nodejs
+    (env-allura)~$ cd ~/src/allura
+    (env-allura)~$ npm install
+    (env-allura)~$ npm run build
+
+
+The application server
+~~~~~~~~~~~~~~~~~~~~~~
+
+In order to initialize the Allura database, you'll need to run the following:
+
+For development setup:
+
+.. code-block:: bash
+
+    (env-allura)~/src/allura/Allura$ paster setup-app development.ini
+
+For production setup:
+
+.. code-block:: bash
+
+    (env-allura)~/src/allura/Allura$ ALLURA_TEST_DATA=False paster setup-app development.ini
+
+This shouldn't take too long, but it will start the taskd server doing tons of stuff in the
background.  Once this is done, you can start the application server:
+
+.. code-block:: bash
+
+    (env-allura)~/src/allura/Allura$ gunicorn --reload --paste development.ini  # add --daemon
to run in the background
+
+Next Steps
+^^^^^^^^^^
+
+Go to the Allura webapp running on your `local machine <http://localhost:8080/>`_ port
8080.
+
+* Read :ref:`post-setup-instructions`
+* Ask questions and discuss Allura on the `allura-dev mailing list <http://mail-archives.apache.org/mod_mbox/allura-dev/>`_
+* Run the test suite (slow): :code:`$ ALLURA_VALIDATION=none ./run_tests`
+* File bug reports at https://forge-allura.apache.org/p/allura/tickets/new/ (login required)
+* Contribute code according to :ref:`this guide <contributing>`

http://git-wip-us.apache.org/repos/asf/allura/blob/53b18cd8/Allura/docs/getting_started/installation.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/installation.rst b/Allura/docs/getting_started/installation.rst
index 4b22e1f..4df2994 100644
--- a/Allura/docs/getting_started/installation.rst
+++ b/Allura/docs/getting_started/installation.rst
@@ -22,222 +22,7 @@ Installation
 .. contents::
    :local:
 
-.. _step-by-step-install:
-
-Step-by-Step Installation
--------------------------
-
-For a simpler setup using Docker images, see :ref:`docker-install` instead.
-
-In these instructions, we'll use `VirtualBox <http://www.virtualbox.org>`__ and `Ubuntu
16.04 <http://ubuntu.com>`_ (15.04 works too) to create a disposable sandbox for Allura
development/testing.  Allura should work on other Linux systems (including OSX), but setting
up all the dependencies will be different.
-
-* Download and install `VirtualBox <http://www.virtualbox.org/wiki/Downloads>`__ for
your platform.
-
-* Download a minimal `Ubuntu 16.04 64-bit ISO <https://help.ubuntu.com/community/Installation/MinimalCD>`_.
-
-* Create a new virtual machine in Virtual Box, selecting Ubuntu (64 bit) as the OS type.
 The rest of the wizards' defaults are fine.
-
-* When you launch the virtual machine for the first time, you will be prompted to attach
your installation media.  Browse to the :file:`mini.iso` that you downloaded earlier.
-
-* After a text-only installation, you may end up with a blank screen and blinking cursor.
 Press :code:`Alt-F1` to switch to the first console.
-
-* Consult `available documentation <https://help.ubuntu.com/>`_ for help installing
Ubuntu.
-
-
-System Packages
-^^^^^^^^^^^^^^^
-
-Before we begin, you'll need to install some system packages.
-
-.. code-block:: bash
-
-    ~$ sudo apt-get install git-core python2.7-dev libssl-dev libldap2-dev libsasl2-dev libjpeg8-dev
zlib1g-dev libffi-dev
-
-To install MongoDB, follow the instructions `here <https://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/>`_.
-
-Optional, for SVN support:
-
-.. code-block:: bash
-
-    ~$ sudo apt-get install subversion python-svn
-
-Setting up a virtual python environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The first step to installing the Allura platform is installing a virtual environment via
`virtualenv <https://virtualenv.pypa.io/en/latest/>`_.  This helps keep our distribution
python installation clean.
-
-.. code-block:: bash
-
-    ~$ sudo apt-get install python-pip
-    ~$ sudo pip install virtualenv
-
-Once you have virtualenv installed, you need to create a virtual environment.  We'll call
our Allura environment 'env-allura'.
-
-.. code-block:: bash
-
-    ~$ virtualenv env-allura
-
-This gives us a nice, clean environment into which we can install all the allura dependencies.
-In order to use the virtual environment, you'll need to activate it:
-
-.. code-block:: bash
-
-    ~$ . env-allura/bin/activate
-
-You'll need to do this whenever you're working on the Allura codebase so you may want to
consider adding it to your :file:`~/.bashrc` file.
-
-Creating the log directory
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: bash
-
-    (env-allura)~$ sudo mkdir -p /var/log/allura
-    (env-allura)~$ sudo chown $(whoami) /var/log/allura
-
-Installing the Allura code and dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Now we can get down to actually getting the Allura code and dependencies downloaded and ready
to go.  If you don't have the source code yet, run:
-
-.. code-block:: bash
-
-    (env-allura)~$ mkdir src
-    (env-allura)~$ cd src
-    (env-allura)~/src$ git clone https://git-wip-us.apache.org/repos/asf/allura.git allura
-
-If you already reading this file from an Allura release or checkout, you're ready to continue.
-
-Although the application :file:`setup.py` files define a number of dependencies, the :file:`requirements.txt`
files are currently the authoritative source, so we'll use those with `pip <https://pip.pypa.io/en/stable/>`_
to make sure the correct versions are installed.
-
-.. code-block:: bash
-
-    (env-allura)~/src$ cd allura
-    (env-allura)~/src/allura$ pip install -r requirements.txt
-
-This will take a while.  If you get an error from pip, it is typically a temporary download
error.  Just run the command again and it will quickly pass through the packages it already
downloaded and then continue.
-
-Optional, for SVN support: symlink the system pysvn package into our virtual environment
-
-.. code-block:: bash
-
-    (env-allura)~/src/allura$ ln -s /usr/lib/python2.7/dist-packages/pysvn ~/env-allura/lib/python2.7/site-packages/
-
-Next, run this to set up all the Allura tools:
-
-.. code-block:: bash
-
-    (env-allura)~/src/allura$ ./rebuild-all.bash
-
-.. note::
-
-    If you only want to use a few tools, run this instead:
-
-    .. code-block:: bash
-
-        (env-allura)~/src/allura$ cd Allura
-        (env-allura)~/src/allura/Allura$ python setup.py develop
-        (env-allura)~/src/allura/Allura$ cd ../ForgeWiki   # required tool
-        (env-allura)~/src/allura/ForgeWiki$ python setup.py develop
-        # repeat for any other tools you want to use
-
-Initializing the environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Allura forge consists of several components, all of which need to be running to have
full functionality.
-
-SOLR search and indexing server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We have a custom config ready for use.
-
-.. code-block:: bash
-
-    (env-allura)~$ cd tmp
-    (env-allura)/tmp$ sudo apt-get install default-jre-headless unzip
-    (env-allura)/tmp$ wget -nv http://archive.apache.org/dist/lucene/solr/5.3.1/solr-5.3.1.tgz
-    (env-allura)/tmp$ tar xvf solr-5.3.1.tgz solr-5.3.1/bin/install_solr_service.sh --strip-components=2
-    (env-allura)/tmp$ sudo ./install_solr_service.sh solr-5.3.1.tgz
-
-    (env-allura)/tmp$ cd ~/src/allura
-    (env-allura)~/src/allura$ sudo -H -u solr bash -c 'cp -R solr_config/allura/ /var/solr/data/'
-    (env-allura)~/src/allura$ sudo service solr start
-
-
-Create code repo directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The default configuration stores repos in :file:`/srv`, so we need to create those directories:
-
-.. code-block:: bash
-
-    ~$ sudo mkdir /srv/{git,svn,hg}
-    ~$ sudo chown $USER /srv/{git,svn,hg}
-    ~$ sudo chmod 775 /srv/{git,svn,hg}
-
-If you don't have :code:`sudo` permission or just want to store them somewhere else, change
the :file:`/srv` paths in :file:`development.ini`
-
-If you want to set up remote access to the repositories, see :ref:`scm_hosting`
-
-Allura task processing
-~~~~~~~~~~~~~~~~~~~~~~
-
-Allura uses a background task service called "taskd" to do async tasks like sending emails,
and indexing data into solr, etc.  Let's get it running
-
-.. code-block:: bash
-
-    (env-allura)~$ cd ~/src/allura/Allura
-    (env-allura)~/src/allura/Allura$ nohup paster taskd development.ini > /var/log/allura/taskd.log
2>&1 &
-
-
-A few more steps, if using git
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you're using a released version of Allura, these are already done for you.  This transpiles
JS into a version all browsers support.
-For non-Ubuntu installations see https://nodejs.org/en/download/package-manager/ for other
options to replace the first line here:
-
-.. code-block:: bash
-
-    (env-allura)~$ curl --silent --location https://deb.nodesource.com/setup_4.x | sudo bash
-
-    (env-allura)~$ sudo apt-get install nodejs
-    (env-allura)~$ cd ~/src/allura
-    (env-allura)~$ npm install
-    (env-allura)~$ npm run build
-
-
-The application server
-~~~~~~~~~~~~~~~~~~~~~~
-
-In order to initialize the Allura database, you'll need to run the following:
-
-For development setup:
-
-.. code-block:: bash
-
-    (env-allura)~/src/allura/Allura$ paster setup-app development.ini
-
-For production setup:
-
-.. code-block:: bash
-
-    (env-allura)~/src/allura/Allura$ ALLURA_TEST_DATA=False paster setup-app development.ini
-
-This shouldn't take too long, but it will start the taskd server doing tons of stuff in the
background.  Once this is done, you can start the application server:
-
-.. code-block:: bash
-
-    (env-allura)~/src/allura/Allura$ gunicorn --reload --paste development.ini  # add --daemon
to run in the background
-
-Next Steps
-^^^^^^^^^^
-
-Go to the Allura webapp running on your `local machine <http://localhost:8080/>`_ port
8080.
-(If you're running this inside a VM, you'll probably have to configure the port forwarding
settings)
-
-* Read :ref:`post-setup-instructions`
-* Ask questions and discuss Allura on the `allura-dev mailing list <http://mail-archives.apache.org/mod_mbox/allura-dev/>`_
-* Run the test suite (slow): :code:`$ ALLURA_VALIDATION=none ./run_tests`
-* File bug reports at https://forge-allura.apache.org/p/allura/tickets/new/ (login required)
-* Contribute code according to :ref:`this guide <contributing>`
+To install without Docker requires installing and configuring many services.  See :ref:`step-by-step-install`.
 
 .. _docker-install:
 
@@ -253,6 +38,13 @@ Install `Docker <http://docs.docker.com/installation/>`_ and `Docker
Compose <ht
 On Linux, you may need to `create a docker group <https://docs.docker.com/engine/installation/linux/ubuntulinux/#create-a-docker-group>`_.
 On Mac, make sure
 you're in a directory that Virtual Box shares through to the VM (by default, anywhere in
your home directory works).
 
+.. note::
+
+   For a production-ready Allura, follow the instructions in :file:`Allura/production-docker-example.ini`.
+   Then run :code:`export COMPOSE_FILE=docker-compose-prod.yml` and continue running the
following commands.
+   This will give you HTTPS, settings for better performance and no debugging, and only expose
necessary ports.
+
+
 Run the following commands in your allura directory:
 
 Build/fetch all required images:

http://git-wip-us.apache.org/repos/asf/allura/blob/53b18cd8/README.markdown
----------------------------------------------------------------------
diff --git a/README.markdown b/README.markdown
index 3245ddd..b0bbc4b 100644
--- a/README.markdown
+++ b/README.markdown
@@ -40,8 +40,8 @@ Website: <https://allura.apache.org/>
 
 Before hacking on Allura, you’ll need to get an Allura instance up and running so you can
see and test the changes you make. You can install Allura from scratch, or by using our Docker
container images. Instructions for these approaches can be found here:
 
-- [Install from scratch](https://forge-allura.apache.org/docs/getting_started/installation.html#step-by-step-install)
-- [Install using Docker](https://forge-allura.apache.org/docs/getting_started/installation.html#docker-install)
+- [Install using Docker](https://forge-allura.apache.org/docs/getting_started/installation.html)
+- [Install from scratch](https://forge-allura.apache.org/docs/getting_started/install_each_step.html)
 
 To install Allura, see `Allura/docs/getting_started/installation.rst` or <https://forge-allura.apache.org/docs/getting_started/installation.html>.
 


Mime
View raw message