Infra
/
lemur
5
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #167 from forkd/master 

minor changes in quickstart guide
This commit is contained in:
kevgliss 2015-12-02 14:51:07 -08:00
parent 5ba1176f14 edbe5a254b
commit 837bfc3aa5
1 changed files with 47 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/quickstart/index.rst
View File

@ -1,38 +1,35 @@
Quickstart Quickstart
********** **********
This guide will step you through setting up a Python-based virtualenv, installing the required packages, and configuring the basic web service. This guide will step you through setting up a Python-based virtualenv, installing the required packages, and configuring the basic web service. This guide assumes a clean Ubuntu 14.04 instance, commands may differ based on the OS and configuration being used.
This guide assumes a clean Ubuntu 14.04 instance, commands may differ based on the OS and configuration being used.
Pressed for time? See the Lemur docker file on `Github <https://github.com/Netflix/lemur-docker>`_. Pressed for time? See the Lemur docker file on `Github <https://github.com/Netflix/lemur-docker>`_.
Dependencies Dependencies
------------ ------------
Some basic prerequisites which you'll need in order to run Lemur: Some basic prerequisites which you'll need in order to run Lemur:
* A UNIX-based operating system. We test on Ubuntu, develop on OS X * A UNIX-based operating system (we test on Ubuntu, develop on OS X)
* Python 2.7 * Python 2.7
* PostgreSQL * PostgreSQL
* Nginx * Nginx
.. note:: Lemur was built with in AWS in mind. This means that things such as databases (RDS), mail (SES), and TLS (ELB), .. note:: Lemur was built with in AWS in mind. This means that things such as databases (RDS), mail (SES), and TLS (ELB), are largely handled for us. Lemur does **not** require AWS to function. Our guides and documentation try to be be as generic as possible and are not intended to document every step of launching Lemur into a given environment.
are largely handled for us. Lemur does **not** require AWS to function. Our guides and documentation try to be
be as generic as possible and are not intended to document every step of launching Lemur into a given environment.
Installing Build Dependencies Installing Build Dependencies
----------------------------- -----------------------------
If installing Lemur on a bare Ubuntu OS you will need to grab the following packages so that Lemur can correctly build it's If installing Lemur on a bare Ubuntu OS you will need to grab the following packages so that Lemur can correctly build it's dependencies:
dependencies:
.. code-block:: bash .. code-block:: bash
$ sudo apt-get update $ sudo apt-get update
$ sudo apt-get install install nodejs-legacy python-pip python-dev libpq-dev build-essential libssl-dev libffi-dev nginx git supervisor npm postgresql $ sudo apt-get install install nodejs-legacy python-pip python-dev libpq-dev build-essential libssl-dev libffi-dev nginx git supervisor npm postgresql
.. note:: PostgreSQL is only required if your database is going to be on the same host as the webserver. npm is needed if you're installing the Lemur source (e.g. from git). .. note:: PostgreSQL is only required if your database is going to be on the same host as the webserver. npm is needed if you're installing Lemur from the source (e.g., from git).
Now, install Python ``virtualenv`` package: Now, install Python ``virtualenv`` package:
@ -44,14 +41,14 @@ Now, install Python ``virtualenv`` package:
Setting up an Environment Setting up an Environment
------------------------- -------------------------
In this guide Lemur will be installed in ``/www``, so you need to create that structure first: In this guide, Lemur will be installed in ``/www``, so you need to create that structure first:
.. code-block:: bash .. code-block:: bash
$ sudo mkdir /www $ sudo mkdir /www
$ cd /www $ cd /www
Clone Lemur inside the just created directory and give yourself write permission (we assume lemur is the user): Clone Lemur inside the just created directory and give yourself write permission (we assume ``lemur`` is the user):
.. code-block:: bash .. code-block:: bash
@ -66,8 +63,7 @@ Create the virtual environment, activate it and enter the Lemur's directory:
$ source /www/lemur/bin/activate $ source /www/lemur/bin/activate
$ cd lemur $ cd lemur
.. note:: Activating the environment adjusts your PATH, so that things like pip now .. note:: Activating the environment adjusts your PATH, so that things like pip now install into the virtualenv by default.
install into the virtualenv by default.
Installing from Source Installing from Source
@ -91,9 +87,7 @@ And then run:
Creating a configuration Creating a configuration
------------------------ ------------------------
Before we run Lemur we must create a valid configuration file for it. Before we run Lemur, we must create a valid configuration file for it. The Lemur command line interface comes with a simple command to get you up and running quickly.
The Lemur cli comes with a simple command to get you up and running quickly.
Simply run: Simply run:
@ -101,98 +95,85 @@ Simply run:
$ lemur create_config $ lemur create_config
.. note:: This command will create a default configuration under `~/.lemur/lemur.conf.py` you .. note:: This command will create a default configuration under ``~/.lemur/lemur.conf.py`` you can specify this location by passing the ``config_path`` parameter to the ``create_config`` command.
can specify this location by passing the `config_path` parameter to the `create_config` command.
You can specify `-c` or `--config` to any Lemur command to specify the current environment You can specify ``-c`` or ``--config`` to any Lemur command to specify the current environment you are working in. Lemur will also look under the environmental variable ``LEMUR_CONF`` should that be easier to setup in your environment.
you are working in. Lemur will also look under the environmental variable `LEMUR_CONF` should
that be easier to setup in your environment.
Update your configuration Update your configuration
------------------------- -------------------------
Once created you will need to update the configuration file with information about your environment, Once created, you will need to update the configuration file with information about your environment, such as which database to talk to, where keys are stored etc.
such as which database to talk to, where keys are stored etc..
.. note:: If you are unfamiliar with with the SQLALCHEMY_DATABASE_URI string it can be broken up like so: .. note:: If you are unfamiliar with with the SQLALCHEMY_DATABASE_URI string it can be broken up like so:
postgresql://userame:password@<database-fqdn>:<database-port>/<database-name> ``postgresql://userame:password@<database-fqdn>:<database-port>/<database-name>``
Setup Postgres Setup Postgres
-------------- --------------
For production a dedicated database is recommended, for this guide we will assume postgres has been installed and is on For production, a dedicated database is recommended, for this guide we will assume postgres has been installed and is on the same machine that Lemur is installed on.
the same machine that Lemur is installed on.
First, set a password for the postgres user. For this guide, we will use **lemur** as an example but you should use the database password generated by Lemur:: First, set a password for the postgres user. For this guide, we will use ``lemur`` as an example but you should use the database password generated by Lemur:
.. code-block:: bash
$ sudo -u postgres psql postgres $ sudo -u postgres psql postgres
# \password postgres # \password postgres
Enter new password: lemur Enter new password: lemur
Enter it again: lemur Enter it again: lemur
Once successful enter CTRL-D to exit the postgres shell. Once successful, type CTRL-D to exit the Postgres shell.
Next, we will create our new database:: Next, we will create our new database:
.. code-block:: bash
$ sudo -u postgres createdb lemur $ sudo -u postgres createdb lemur
.. _InitializingLemur: .. _InitializingLemur:
Set a password for lemur user inside Postgres:: Set a password for lemur user inside Postgres:
.. code-block:: bash
$ sudo -u postgres psql postgres $ sudo -u postgres psql postgres
\password lemur \password lemur
Enter new password: lemur Enter new password: lemur
Enter it again: lemur Enter it again: lemur
Again, enter CTRL-D to exit the postgres shell. Again, enter CTRL-D to exit the Postgres shell.
Initializing Lemur Initializing Lemur
------------------ ------------------
Lemur provides a helpful command that will initialize your database for you. It creates a default user (lemur) that is Lemur provides a helpful command that will initialize your database for you. It creates a default user (``lemur``) that is used by Lemur to help associate certificates that do not currently have an owner. This is most commonly the case when Lemur has discovered certificates from a third party source. This is also a default user that can be used to administer Lemur.
used by Lemur to help associate certificates that do not currently have an owner. This is most commonly the case when
Lemur has discovered certificates from a third party source. This is also a default user that can be used to
administer Lemur.
In addition to creating a new user, Lemur also creates a few default email notifications. These notifications are based In addition to creating a new user, Lemur also creates a few default email notifications. These notifications are based on a few configuration options such as ``LEMUR_SECURITY_TEAM_EMAIL``. They basically guarantee that every certificate within Lemur will send one expiration notification to the security team.
on a few configuration options such as `LEMUR_SECURITY_TEAM_EMAIL`. They basically guarantee that every ceritificate within
Lemur will send one expiration notification to the security team.
Additional notifications can be created through the UI or API. Additional notifications can be created through the UI or API. See :ref:`Creating Notifications <CreatingNotifications>` and :ref:`Command Line Interface <CommandLineInterface>` for details.
See :ref:`Creating Notifications <CreatingNotifications>` and :ref:`Command Line Interface <CommandLineInterface>` for details.
**Make note of the password used as this will be used during first login to the Lemur UI** **Make note of the password used as this will be used during first login to the Lemur UI.**
.. code-block:: bash .. code-block:: bash
$ lemur db init $ lemur db init
.. code-block:: bash
$ lemur init $ lemur init
.. note:: It is recommended that once the 'lemur' user is created that you create individual users for every day access. .. note:: It is recommended that once the ``lemur`` user is created that you create individual users for every day access. There is currently no way for a user to self enroll for Lemur access, they must have an administrator create an account for them or be enrolled automatically through SSO. This can be done through the CLI or UI. See :ref:`Creating Users <CreatingUsers>` and :ref:`Command Line Interface <CommandLineInterface>` for details.
There is currently no way for a user to self enroll for Lemur access, they must have an administrator create an account
for them or be enrolled automatically through SSO. This can be done through the CLI or UI.
See :ref:`Creating Users <CreatingUsers>` and :ref:`Command Line Interface <CommandLineInterface>` for details
Setup a Reverse Proxy Setup a Reverse Proxy
--------------------- ---------------------
By default, Lemur runs on port 8000. Even if you change this, under normal conditions you won't be able to bind to By default, Lemur runs on port 8000. Even if you change this, under normal conditions you won't be able to bind to port 80. To get around this (and to avoid running Lemur as a privileged user, which you shouldn't), we need setup a simple web proxy. There are many different web servers you can use for this, we like and recommend Nginx.
port 80. To get around this (and to avoid running Lemur as a privileged user, which you shouldn't), we need setup a
simple web proxy. There are many different web servers you can use for this, we like and recommend Nginx.
Proxying with Nginx Proxying with Nginx
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
You'll use the builtin HttpProxyModule within Nginx to handle proxying. Edit the ``/etc/nginx/sites-available/default`` file according to the lines below You'll use the builtin ``HttpProxyModule`` within Nginx to handle proxying. Edit the ``/etc/nginx/sites-available/default`` file according to the lines below
:: ::
@ -214,7 +195,9 @@ You'll use the builtin HttpProxyModule within Nginx to handle proxying. Edit th
.. note:: See :doc:`../production/index` for more details on using Nginx. .. note:: See :doc:`../production/index` for more details on using Nginx.
After making these changes, restart Nginx service to apply them:: After making these changes, restart Nginx service to apply them:
.. code-block:: bash
$ sudo service nginx restart $ sudo service nginx restart
@ -225,7 +208,7 @@ Starting the Web Service
Lemur provides a built-in web server (powered by gunicorn and eventlet) to get you off the ground quickly. Lemur provides a built-in web server (powered by gunicorn and eventlet) to get you off the ground quickly.
To start the web server, you simply use ``lemur start``. If you opted to use an alternative configuration path To start the web server, you simply use ``lemur start``. If you opted to use an alternative configuration path
you can pass that via the --config option. you can pass that via the ``--config`` option.
.. note:: .. note::
You can login with the default user created during :ref:`Initializing Lemur <InitializingLemur>` or any other You can login with the default user created during :ref:`Initializing Lemur <InitializingLemur>` or any other
@ -237,21 +220,19 @@ you can pass that via the --config option.
# the correct host and port! # the correct host and port!
lemur --config=/etc/lemur.conf.py start -b 127.0.0.1:8000 lemur --config=/etc/lemur.conf.py start -b 127.0.0.1:8000
You should now be able to test the web service by visiting `http://localhost:5000/`. You should now be able to test the web service by visiting ``http://localhost:5000/``.
Running Lemur as a Service Running Lemur as a Service
-------------------------- --------------------------
We recommend using whatever software you are most familiar with for managing Lemur processes. One option is We recommend using whatever software you are most familiar with for managing Lemur processes. One option is `Supervisor <http://supervisord.org/>`_.
`Supervisor <http://supervisord.org/>`_.
Configure ``supervisord`` Configure ``supervisord``
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Configuring Supervisor couldn't be more simple. Just point it to the ``lemur`` executable in your virtualenv's bin/ Configuring Supervisor couldn't be more simple. Just point it to the ``lemur`` executable in your virtualenv's ``bin/`` folder and you're good to go.
folder and you're good to go.
:: ::
@ -270,8 +251,7 @@ See :ref:`Using Supervisor <UsingSupervisor>` for more details on using Supervis
Syncing Syncing
------- -------
Lemur uses periodic sync tasks to make sure it is up-to-date with its environment. As always things can change outside Lemur uses periodic sync tasks to make sure it is up-to-date with its environment. As always, things can change outside of Lemur, but we do our best to reconcile those changes, for example, using Cron:
of Lemur, but we do our best to reconcile those changes.
.. code-block:: bash .. code-block:: bash
@ -283,30 +263,26 @@ of Lemur, but we do our best to reconcile those changes.
Additional Utilities Additional Utilities
-------------------- --------------------
If you're familiar with Python you'll quickly find yourself at home, and even more so if you've used Flask. The If you're familiar with Python you'll quickly find yourself at home, and even more so if you've used Flask. The ``lemur`` command is just a simple wrapper around Flask's ``manage.py``, which means you get all of the power and flexibility that goes with it.
``lemur`` command is just a simple wrapper around Flask's ``manage.py``, which means you get all of the
power and flexibility that goes with it.
Some of the features which you'll likely find useful are: Some of the features which you'll likely find useful are listed below.
lock lock
~~~~ ~~~~
Encrypts sensitive key material - This is most useful for storing encrypted secrets in source code. Encrypts sensitive key material - this is most useful for storing encrypted secrets in source code.
unlock unlock
~~~~~~ ~~~~~~
Decrypts sensitive key material - Used to decrypt the secrets stored in source during deployment. Decrypts sensitive key material - used to decrypt the secrets stored in source during deployment.
What's Next? What's Next?
------------ ------------
Get familiar with how Lemur works by reviewing the :doc:`../guide/index`. When you're ready Get familiar with how Lemur works by reviewing the :doc:`../guide/index`. When you're ready see :doc:`../production/index` for more details on how to configure Lemur for production.
see :doc:`../production/index` for more details on how to configure Lemur for production.
The above just gets you going, but for production there are several different security considerations to take into account. The above just gets you going, but for production there are several different security considerations to take into account. Remember, Lemur is handling sensitive data and security is imperative.
Remember, Lemur is handling sensitive data and security is imperative.