forked from project-koku/koku
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated readme with basic project information (project-koku#60)
* Updated readme with basic project information
- Loading branch information
1 parent
0467352
commit e802a96
Showing
1 changed file
with
112 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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/ |