fix rst formatting
Fix some indentation and other markup issues in the RST for the documentation. Change-Id: I921445f7120335510ee7b203a2210737012bcdf2 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann
parent
708d09be77
commit
2a176d1d0c
@ -18,8 +18,10 @@ StoryBoard webclient.
|
||||
Installing and Upgrading the API server
|
||||
=======================================
|
||||
|
||||
NOTE: If you are using a Virtual Machine (VM), all commands that begin with
|
||||
``tox`` will need to be preceeded by ``sudo``.
|
||||
.. note::
|
||||
|
||||
If you are using a Virtual Machine (VM), all commands that begin with
|
||||
``tox`` will need to be preceeded by ``sudo``.
|
||||
|
||||
1. To start the API server, make sure you have the following packages installed
|
||||
locally:
|
||||
@ -27,13 +29,16 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with
|
||||
* libpq-dev
|
||||
* libmysqlclient-dev
|
||||
* python-dev
|
||||
* MySQL
|
||||
|
||||
NOTE: MySQL must be >= 5.6::
|
||||
::
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install libpq-dev libmysqlclient-dev python-dev
|
||||
sudo apt-get install mysql-server-5.7 #Here you will be asked to set a password
|
||||
mysql --version
|
||||
sudo apt-get update
|
||||
sudo apt-get install libpq-dev libmysqlclient-dev python-dev
|
||||
sudo apt-get install mysql-server-5.7 #Here you will be asked to set a password
|
||||
mysql --version
|
||||
|
||||
.. note:: MySQL must be >= 5.6
|
||||
|
||||
|
||||
2. Clone the StoryBoard repository::
|
||||
@ -44,13 +49,16 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with
|
||||
|
||||
3. Add MySQL user and create database:
|
||||
|
||||
NOTE: You will need to replace the ``$DB_USER`` with ``root``.
|
||||
It will prompt for a password; this is
|
||||
the password you set when you ran
|
||||
``sudo apt-get mysql-server-5.6`` in step 1::
|
||||
.. note::
|
||||
|
||||
mysql -u $DB_USER -p -e 'DROP DATABASE IF EXISTS storyboard;'
|
||||
mysql -u $DB_USER -p -e 'CREATE DATABASE storyboard;'
|
||||
You will need to replace the ``$DB_USER`` with ``root``. It
|
||||
will prompt for a password; this is the password you set when
|
||||
you ran ``sudo apt-get mysql-server-5.6`` in step 1.
|
||||
|
||||
::
|
||||
|
||||
mysql -u $DB_USER -p -e 'DROP DATABASE IF EXISTS storyboard;'
|
||||
mysql -u $DB_USER -p -e 'CREATE DATABASE storyboard;'
|
||||
|
||||
|
||||
4. Copy the sample configuration file::
|
||||
@ -69,7 +77,7 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with
|
||||
|
||||
sudo apt-get install python-pip
|
||||
pip install tox
|
||||
|
||||
|
||||
7. Upgrade DB schema to the latest version::
|
||||
|
||||
tox -e venv "storyboard-db-manage --config-file ./etc/storyboard.conf upgrade head"
|
||||
@ -87,12 +95,12 @@ Installing the Javascript-based web client
|
||||
1. To build and start the web client, you will need this dependency set
|
||||
installed locally:
|
||||
|
||||
* Python 2.6 or 2.7
|
||||
* Node.js v0.10.29 or newer (see https://nodejs.org/en/download/package-manager/ for more information on getting the right package for your distribution)
|
||||
* npm v1.3.10 or newer (this will be bundled with Node.js)
|
||||
* Python 2.6 or 2.7
|
||||
* Node.js v0.10.29 or newer (see https://nodejs.org/en/download/package-manager/ for more information on getting the right package for your distribution)
|
||||
* npm v1.3.10 or newer (this will be bundled with Node.js)
|
||||
|
||||
(Ubuntu Trusty packages are sufficient, even though they indicate an older
|
||||
version. MySQL must be >= 5.6.)
|
||||
(Ubuntu Trusty packages are sufficient, even though they indicate an older
|
||||
version. MySQL must be >= 5.6.)
|
||||
|
||||
|
||||
2. Clone the StoryBoard webclient::
|
||||
@ -101,24 +109,20 @@ Installing the Javascript-based web client
|
||||
cd storyboard-webclient
|
||||
|
||||
|
||||
Do one of the following that applies to you:
|
||||
3. Do **one** of the following that applies to you.
|
||||
|
||||
3a. Run a local development server, which uses the localhost API::
|
||||
a. Run a local development server, which uses the localhost API::
|
||||
|
||||
tox -egrunt_no_api -- serve
|
||||
tox -egrunt_no_api -- serve
|
||||
|
||||
or...
|
||||
b. Run a local development server, which binds to a specific IP and
|
||||
consumes the localhost API::
|
||||
|
||||
3b. Run a local development server, which binds to a specific IP and
|
||||
consumes the localhost API::
|
||||
tox -egrunt_no_api -- serve --hostname 0.0.0.0
|
||||
|
||||
tox -egrunt_no_api -- serve --hostname 0.0.0.0
|
||||
c. Run a local development server, which uses the production API::
|
||||
|
||||
or...
|
||||
|
||||
3c. Run a local development server, which uses the production API::
|
||||
|
||||
tox -egrunt_no_api -- serve:prod
|
||||
tox -egrunt_no_api -- serve:prod
|
||||
|
||||
|
||||
Make user an admin - current bug
|
||||
@ -208,8 +212,10 @@ Optional steps: Seed database with base data
|
||||
Optional steps: Set up the notifications daemon
|
||||
===============================================
|
||||
|
||||
NOTE: If you followed the "Launch the development VM" instuctions
|
||||
above, this step is unnecessary.
|
||||
.. note::
|
||||
|
||||
If you followed the "Launch the development VM" instuctions above,
|
||||
this step is unnecessary.
|
||||
|
||||
1. Install rabbitmq on your development machine::
|
||||
|
||||
|
||||
@ -26,109 +26,110 @@ Test Migration
|
||||
|
||||
1. Obtain a StoryBoard instance
|
||||
|
||||
First you'll need superuser permissions on a StoryBoard instance. Unless
|
||||
you are infra-core or Zara or SotK, the best way to do this is to spin
|
||||
up your own test instance in a VM or somewhere.
|
||||
First you'll need superuser permissions on a StoryBoard instance. Unless
|
||||
you are infra-core or Zara or SotK, the best way to do this is to spin
|
||||
up your own test instance in a VM or somewhere.
|
||||
|
||||
There are instructions on how to do that [here][0]. I won't go into detail
|
||||
here on the ins and outs of getting set up. When you have an up-to-date
|
||||
database you'll need to log in via the webclient. Upon successfully logging
|
||||
in, connect to your database with the mysql command line client, providing
|
||||
your password as prompted:
|
||||
There are instructions on how to do that in :doc:`/install/development`.
|
||||
I won't go into detail
|
||||
here on the ins and outs of getting set up. When you have an up-to-date
|
||||
database you'll need to log in via the webclient. Upon successfully logging
|
||||
in, connect to your database with the mysql command line client, providing
|
||||
your password as prompted::
|
||||
|
||||
mysql -u $YOUR_DB_USER -p
|
||||
mysql -u $YOUR_DB_USER -p
|
||||
|
||||
Then run the following:
|
||||
Then run the following::
|
||||
|
||||
connect $YOUR_DB_NAME;
|
||||
update users set is_superuser=1;
|
||||
connect $YOUR_DB_NAME;
|
||||
update users set is_superuser=1;
|
||||
|
||||
This will make every user that has so far logged in to have superuser
|
||||
permissions.
|
||||
This will make every user that has so far logged in to have superuser
|
||||
permissions.
|
||||
|
||||
[0]: https://docs.openstack.org/infra/storyboard/install/development.html
|
||||
* (optional) Obtain a sanitised dump of the production database
|
||||
|
||||
1.1 (optional) Obtain a sanitised dump of the production database
|
||||
If you want to test migrating against production data, you'll need that
|
||||
data. The way to obtain this is to ask an infra core nicely.
|
||||
|
||||
If you want to test migrating against production data, you'll need that
|
||||
data. The way to obtain this is to ask an infra core nicely.
|
||||
You can use the provided .sql file to recreate the production database
|
||||
in your local instance::
|
||||
|
||||
You can use the provided .sql file to recreate the production database
|
||||
in your local instance:
|
||||
mysql -u $YOUR_DB_USER -p < /path/to/db/dump.sql
|
||||
|
||||
mysql -u $YOUR_DB_USER -p < /path/to/db/dump.sql
|
||||
.. warning::
|
||||
|
||||
> WARNING: This database will have the name `storyboard`, and will
|
||||
> obliterate the contents of any database you already have with the
|
||||
> same name.
|
||||
This database will have the name `storyboard`, and will obliterate
|
||||
the contents of any database you already have with the same name.
|
||||
|
||||
2. Create the StoryBoard project
|
||||
|
||||
Log in to the webclient for your StoryBoard instance. When logged in,
|
||||
click the "Create New..." button, and pick "Project". Give the project
|
||||
a name (in storyboard.o.o this will match the git repository name, so
|
||||
you may as well use that) and a description.
|
||||
Log in to the webclient for your StoryBoard instance. When logged in,
|
||||
click the "Create New..." button, and pick "Project". Give the project
|
||||
a name (in storyboard.o.o this will match the git repository name, so
|
||||
you may as well use that) and a description.
|
||||
|
||||
When you are happy with the name and description, and both are outlined
|
||||
in green, click "Create Project".
|
||||
When you are happy with the name and description, and both are outlined
|
||||
in green, click "Create Project".
|
||||
|
||||
3. Migrate!
|
||||
You can do this with the following command:
|
||||
|
||||
You can do this with the following command::
|
||||
|
||||
tox -e venv "storyboard-migrate
|
||||
--config-file etc/storyboard.conf
|
||||
--from-project $PROJECT_IN_LAUNCHPAD
|
||||
--to-project $PROJECT_IN_STORYBOARD"
|
||||
|
||||
Here, `$PROJECT_IN_LAUNCHPAD` should be replaced by the name of the
|
||||
project in Launchpad, for example `monasca`. Similarly,
|
||||
`$PROJECT_IN_STORYBOARD` should be replaced the name of the project
|
||||
you are importing into in StoryBoard, for example `openstack/monasca`.
|
||||
Here, `$PROJECT_IN_LAUNCHPAD` should be replaced by the name of the
|
||||
project in Launchpad, for example `monasca`. Similarly,
|
||||
`$PROJECT_IN_STORYBOARD` should be replaced the name of the project
|
||||
you are importing into in StoryBoard, for example `openstack/monasca`.
|
||||
|
||||
Then you must wait for some time to pass whilst the project is
|
||||
migrated. You can watch the output if you like. Sometimes it will
|
||||
crash with a traceback saying the database object already exists.
|
||||
Then you must wait for some time to pass whilst the project is
|
||||
migrated. You can watch the output if you like. Sometimes it will
|
||||
crash with a traceback saying the database object already exists.
|
||||
|
||||
If this happens, then your migration test has FAILED and you need
|
||||
to go shout at SotK to fix this bug (or fix it yourself if you have
|
||||
the spare time to help).
|
||||
If this happens, then your migration test has FAILED and you need
|
||||
to go shout at SotK to fix this bug (or fix it yourself if you have
|
||||
the spare time to help).
|
||||
|
||||
Sometimes it might break in other ways for some reason. If this
|
||||
happens, then your migration test has FAILED and you have found a
|
||||
new and exciting bug. Report it in #storyboard and maybe on
|
||||
StoryBoard somewhere and try to fix it if you like.
|
||||
Sometimes it might break in other ways for some reason. If this
|
||||
happens, then your migration test has FAILED and you have found a
|
||||
new and exciting bug. Report it in #storyboard and maybe on
|
||||
StoryBoard somewhere and try to fix it if you like.
|
||||
|
||||
4. Check everything went smoothly
|
||||
|
||||
At this point you have successfully run a migration. You now need to
|
||||
check that you haven't triggered any of the migration issues we know
|
||||
about currently.
|
||||
At this point you have successfully run a migration. You now need to
|
||||
check that you haven't triggered any of the migration issues we know
|
||||
about currently.
|
||||
|
||||
Check branches as described in 3.1, and also check that you can view
|
||||
the project page in the webclient. Page through the stories to make
|
||||
sure that none of them have content that breaks the webclient.
|
||||
Check branches as described in 3.1, and also check that you can view
|
||||
the project page in the webclient. Page through the stories to make
|
||||
sure that none of them have content that breaks the webclient.
|
||||
|
||||
Check that you can view
|
||||
Check that you can view the URL:
|
||||
|
||||
http://localhost:9000/api/v1/stories?project_id=$YOUR_PROJECT_ID_HERE
|
||||
http://localhost:9000/api/v1/stories?project_id=$YOUR_PROJECT_ID_HERE
|
||||
|
||||
in a web browser. If there is trouble for your browser in rendering
|
||||
that then one of the stories has a non-unicode character in it which
|
||||
will ruin StoryBoard's day.
|
||||
in a web browser. If there is trouble for your browser in rendering
|
||||
that then one of the stories has a non-unicode character in it which
|
||||
will ruin StoryBoard's day.
|
||||
|
||||
If any of these checks don't succeed, then your migration test has
|
||||
FAILED.
|
||||
If any of these checks don't succeed, then your migration test has
|
||||
FAILED.
|
||||
|
||||
If they all succeed, then maybe so has your migration. Test everything
|
||||
you feel like testing, check some of the stories to make sure they look
|
||||
sane. Beware of things that look like a huge mess but are actually just
|
||||
our markdown parser mangling logs that weren't indented by the bug
|
||||
submitter. These aren't an issue but will probably make someone sad.
|
||||
If they all succeed, then maybe so has your migration. Test everything
|
||||
you feel like testing, check some of the stories to make sure they look
|
||||
sane. Beware of things that look like a huge mess but are actually just
|
||||
our markdown parser mangling logs that weren't indented by the bug
|
||||
submitter. These aren't an issue but will probably make someone sad.
|
||||
|
||||
Assuming you tested against production data and everything checked out,
|
||||
the project should be ready to migrate for real. If it wasn't tested
|
||||
against production data, now would be the time test against it as you may
|
||||
discover other bugs.
|
||||
Assuming you tested against production data and everything checked out,
|
||||
the project should be ready to migrate for real. If it wasn't tested
|
||||
against production data, now would be the time test against it as you may
|
||||
discover other bugs.
|
||||
|
||||
The Migration Process
|
||||
---------------------
|
||||
@ -149,9 +150,11 @@ Recently Migrated
|
||||
about where to file bugs now, then go to the 'Bugs' section and set the
|
||||
'bugs are tracked' radio button to the 'somewhere else' option.
|
||||
|
||||
NOTE: Launchpad does not close open bugs or note the new location that
|
||||
people should make comments and updates at which is why it is important
|
||||
to communicate to users, operators, and contributors that you've migrated
|
||||
.. note::
|
||||
|
||||
Launchpad does not close open bugs or note the new location that
|
||||
people should make comments and updates at which is why it is important
|
||||
to communicate to users, operators, and contributors that you've migrated
|
||||
|
||||
Q & A
|
||||
-----
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user