Skip to content

Commit

Permalink
Updated readme with basic project information (project-koku#60)
Browse files Browse the repository at this point in the history
* Updated readme with basic project information
  • Loading branch information
adberglund authored Apr 23, 2018
1 parent 0467352 commit e802a96
Showing 1 changed file with 112 additions and 5 deletions.
117 changes: 112 additions & 5 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,12 +1,119 @@
===========
SaltCellar
===========

|license| |Build Status| |codecov| |Updates| |Python 3| |Docs|

~~~~~
About
~~~~~

SaltCellar's goal is to provide an open source solution for cost management of cloud and hybrid cloud environments. This is offered via a web interface that exposes resource consumption and cost data in easily digestible and filterable views. The project also aims to provide insight into this data and ultimately provide suggested optimizations for reducing cost and eliminating unnecessary resource usage.

Full documentation is available through readthedocs_.


Getting Started
---------------
===============

To deploy a new app on OpenShift Container Platform:
This is a Python project developed using Python 3.6. Make sure you have at least this version installed.

::
Development
===========

To get started developing against SaltCellar first clone a local copy of the git repository. ::

git clone https://github.com/SaltCellar/SaltCellar
cd SaltCellar
oc new-app openshift/templates/django-postgresql-persistent.json --code=https://github.com/SaltCellar/SaltCellar

Developing inside a virtual environment is recommended. A Pipfile is provided. Pipenv is recommended for combining virtual environment (virtualenv) and dependency management (pip). To install pipenv, use pip ::

pip3 install pipenv

Then project dependencies and a virtual environment can be created using ::

pipenv install --dev

To activate the virtual environment run ::

pipenv shell

Configuration
-------------

This project is developed using the Django web framework. Many configuration settings can be read in from a `.env` file. An example file `.env.example` is provided in the repository. To use the defaults simply ::

cp .env.example .env


Modify as you see fit.

Database
--------

PostgreSQL is used as the database backend for SaltCellar. A docker-compose file is provided for creating a local database container. If modifications were made to the .env file the docker-compose file will need to be modified to ensure matching database credentials. Several commands are available for interacting with the database. ::

# This will launch a Postgres container
make start-db

# This will run Django's migrations against the database
make run-migrations

# This will stop and remove a currently running database and run the above commands
make reinitdb

Assuming the default .env file values are used, to access the database directly using psql run ::

psql saltcellar -U saltcellar -h localhost -p 15432

There is a known limitation with docker-compose and Linux environments with SELinux enabled. If a docker container running Postgres is not feasible, it is possible to run Postgres locally as documented in the Postgres tutorial_. The default port for local Postgres installations is `5432`. Make sure to modify the `.env` file accordingly. To initialize the database run ::

make run-migrations

Server
------

To run a local dev Django server you can use ::

make serve

Testing and Linting
-------------------

SaltCellar uses tox to standardize the environment used when running tests. Essentially, tox manages its own virtual environment and a copy of required dependencies to run tests. To ensure a clean tox environement run ::

tox -r

This will rebuild the tox virtual env and then run all tests.

To run unit tests specifically::

tox -e py36

To lint the code base ::

tox -e lint


Contributing
=============

Please refer to contributing.rst_.



.. _readthedocs: http://saltcellar.readthedocs.io/en/latest/
.. _tutorial: https://www.postgresql.org/docs/10/static/tutorial-start.html
.. _contributing.rst: https://github.com/SaltCellar/SaltCellar/blob/master/CONTRIBUTING.rst

.. |license| image:: https://img.shields.io/github/license/SaltCellar/SaltCellar.svg
:target: https://github.com/SaltCellar/SaltCellar/blob/master/LICENSE
.. |Build Status| image:: https://travis-ci.org/SaltCellar/SaltCellar.svg?branch=master
:target: https://travis-ci.org/SaltCellar/SaltCellar
.. |codecov| image:: https://codecov.io/gh/SaltCellar/SaltCellar/branch/master/graph/badge.svg
:target: https://codecov.io/gh/SaltCellar/SaltCellar
.. |Updates| image:: https://pyup.io/repos/github/SaltCellar/SaltCellar/shield.svg?t=1524249231720
:target: https://pyup.io/repos/github/SaltCellar/SaltCellar/
.. |Python 3| image:: https://pyup.io/repos/github/SaltCellar/SaltCellar/python-3-shield.svg?t=1524249231720
:target: https://pyup.io/repos/github/SaltCellar/SaltCellar/
.. |Docs| image:: https://readthedocs.org/projects/saltcellar/badge/
:target: https://saltcellar.readthedocs.io/en/latest/

0 comments on commit e802a96

Please sign in to comment.