From 39a6e884d13f9e3440b8c0cd50f1f6f636a19e4e Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Aug 08 2017 01:17:31 +0000 Subject: Make the README great again --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d5c999 --- /dev/null +++ b/README.md @@ -0,0 +1,182 @@ +Fedora Elections +================ + +`fedora-elections` is a web application written in Python and based on Flask. +It implements the [Range Voting system](http://rangevoting.org "Center for Range Voting"). + +This project was developed using Fedora Project requests but can be easily +adapted to other projects. Fedora Elections is integrated with the Fedora +Account System (FAS). + + +## Creating a development environment + +To work on the Fedora Elections web application, you will need to create a +development environment to test your changes. This is simplified by using +[Vagrant](https://www.vagrantup.com/ "Vagrant by Hashicorp"), a powerful and +useful tool for creating development environments on your workstation. + +### Using Vagrant + +You can quickly start hacking on the Fedora Elections web application using the +Vagrant setup included in the elections repo is super simple. + +First, install Vagrant, the `vagrant-libvirt` plugin, and the `vagrant-sshfs` +plugin from the official Fedora repos: + +``` +sudo dnf install vagrant vagrant-libvirt vagrant-sshfs +``` + +Now, from the main directory (the one with the `Vagrantfile` in it), run the +`vagrant up` command to provision your development environment: + +``` +vagrant up +``` + +When completed, you will be able to SSH into your development virtual machine +with `vagrant ssh` and run the command to start the Fedora Elections server: + +``` +vagrant ssh +[vagrant@localhost ~]$ pushd /vagrant/; ./runserver.py --host "0.0.0.0"; +``` + +Once that is running, go to [localhost:5002](http://localhost:5002/) in your +browser to see your running Fedora Elections test instance. + +### A note about fonts + +Fedora Elections uses web fonts hosted in Fedora's infrastructure that might +not work when hacking locally due to CORS restrictions. If you install the +fonts yourself, the Fedora Elections website will look the same as it would +when deployed to production. + +You can install the fonts with this command. + +``` +sudo dnf install open-sans-fonts +``` + + +## How to launch Fedora Elections + +The following steps will get the rest of the application running. Make sure to +use your Vagrant development environment when following these steps. + +### Prerequisites + +Before launching fedora-elections, the following packages should be installed: + +* `httpd` +* `libxslt` +* `python` +* `python-backports-ssl_match_hostname` +* `python-bunch` +* `python-chardet` +* `python-fedora` +* `python-fedora-flask` +* `python-flask` +* `python-flask-sqlalchemy` +* `python-flask-wtf` +* `python-jinja2` +* `python-kitchen` +* `python-lxml` +* `python-openid` +* `python-ordereddict` +* `python-ordereddict` +* `python-setuptools` +* `python-simplejson` +* `python-six` +* `python-sqlalchemy0.7` +* `python-urllib3` +* `python-wtforms` + +### Get the source code + +This project is hosted on [Pagure](https://pagure.io/elections "Fedora Infrastructure Elections application"). +For convenience, a mirror is also hosted on [GitHub](https://github.com/fedora-infra/elections "fedora-infra/elections: Fedora Infrastructure Elections application"). + +You can obtain the code via: + +``` +git clone https://pagure.io/elections.git +``` + +### Configure the application + +An example configuration file is provided [here](https://pagure.io/elections/blob/master/f/files/fedora-elections.cfg "files/fedora-elections.cfg"). + +### Create database + +Run: + +``` +python createdb.py +``` + +### Starting the app + +There are 2 ways to start the application: + +* Without Apache +* With Apache + +#### Without Apache + +This is useful for a quick development instance, when you don't have to worry +about security yet. Do not run this in production. The server will start on +http://127.0.0.1:5000. + +``` +./runserver +``` + +#### With Apache + +Copy `fedora-elections.conf` to your Apache conf.d directory: + +``` +sudo cp files/fedora-elections.conf /etc/httpd/conf.d/. +``` + +Next, place `fedora-elections.wsgi` in `/var/www`: + +``` +sudo cp files/fedora-elections.wsgi /var/www +``` + +Adjust the Apache configuration file to point to your web directory. Then, +adjust the `.wsgi` file in `/var/www` to point to the `fedora_elections` +directory. + +Place the configuration file in `/etc/fedora-elections/fedora-elections.cfg`. + +``` +sudo mkdir -p /etc/fedora-elections/ +sudo cp files/fedora-elections.cfg /etc/fedora-elections/ +``` + +Now, restart Apache: + +``` +sudo systemctl restart httpd +``` + + +## How to contribute + +As mentioned earlier, this project is primarily hosted on [Pagure](https://pagure.io/elections "Fedora Infrastructure Elections application"). +There is a mirror on [GitHub](https://github.com/fedora-infra/elections "fedora-infra/elections: Fedora Infrastructure Elections application"), +but only for convenience. Pagure is the preferred platform for accepting +contributions. To file an issue, RFE, or other ticket, you must use Pagure. See +other issues already filed [here](https://pagure.io/elections/issues). + +If you are interested in working on this project, ask in [`#fedora-admin`](https://webchat.freenode.net/?channels=fedora-admin) +on irc.freenode.net or say hello on the [Fedora Infrastructure mailing list](https://lists.fedoraproject.org/admin/lists/infrastructure@lists.fedoraproject.org/). + + +## License + +fedora-elections is licensed under the GPLv2. diff --git a/README.rst b/README.rst deleted file mode 100644 index ae0658d..0000000 --- a/README.rst +++ /dev/null @@ -1,175 +0,0 @@ -================ -Fedora Elections -================ - -* What is fedora-election? - -fedora-elections is a web application written in python and based on flask. -It implements the Range Voting system (http://rangevoting.org). - -This project was developed using fedoraproject requests, but, can be easily -adapted to other projects. Fedora-elections is integrated with the Fedora -Account System (FAS). - - -Hacking with Vagrant -==================== -Quickly start hacking on elections using the vagrant setup that is included in -the elections repo is super simple. - -First, install Vagrant and the vagrant-libvirt plugin from the official Fedora -repos:: - - $ sudo dnf install vagrant vagrant-libvirt - -The elections vagrant setup uses vagrant-sshfs for syncing files between your -host and the vagrant dev machine. vagrant-sshfs is not in the Fedora repos -(yet), so we install the vagrant-sshfs plugin from dustymabe's COPR repo:: - - $ sudo dnf copr enable dustymabe/vagrant-sshfs - $ sudo dnf install vagrant-sshfs - -Now, from within main directory (the one with the Vagrantfile in it) of your git -checkout of elections, run the ``vagrant up`` command to provision your dev -environment:: - - $ vagrant up - -When this command is completed (it may take a while) you will be able to ssh -into your dev VM with ``vagrant ssh`` and then run the command to start the -elections server:: - - $ vagrant ssh - [vagrant@localhost ~]$ pushd /vagrant/; ./runserver.py --host "0.0.0.0"; - -Once that is running, simply go to http://localhost:5002/ in your browser on -your host to see your running elections test instance. - -A note about fonts -~~~~~~~~~~~~~~~~~~ -Fedora elections uses webfonts pulled down from Fedora infrastructure that might -not work when hacking locally due to CORS resctrictions. Installing the fonts on -the system that you are looking at the elections website on will be the same as -when it gets deployed to prod. Install the required fonts on Fedora with: - - sudo dnf install open-sans-fonts - - -Running from a checkout: -======================== - -Install Prerequisites ---------------------- -Before launching fedora-elections, the following packages should be installed: - - httpd - - libxslt - - python - - python-backports-ssl_match_hostname - - python-bunch - - python-chardet - - python-fedora - - python-fedora-flask - - python-flask - - python-flask-sqlalchemy - - python-flask-wtf - - python-jinja2 - - python-kitchen - - python-lxml - - python-openid - - python-ordereddict - - python-ordereddict - - python-setuptools - - python-simplejson - - python-six - - python-sqlalchemy0.7 - - python-urllib3 - - python-wtforms - - -Get the source code -------------------- -The project is hosted on https://fedorahosted.org/ - -More precisely at: https://fedorahosted.org/elections - -You can obtain the code via: - - :: - - git clone http://git.fedorahosted.org/git/elections.git - -For commodity reason, a clone is available on github: -https://github.com/fedora-infra/elections - - -Configure the application -------------------------- -An example configuration file is provided at: ``files/fedora-elections.cfg`` - - -Create a database ------------------ -Run: - - :: - - python createdb.py - - -Starting the Application ------------------------- - -There are 2 ways to start the application: - * without apache - * with apache - - -* How to start without apache on http://127.0.0.1:5000 (useful for development): - - :: - - ./runserver - - -* How to start with http - - Next copy the file ``fedora-elections.conf`` file to your apache conf.d - directory: - - :: - - sudo cp files/fedora-elections.conf /etc/httpd/conf.d/. - - Place the file ``fedora-elections.wsgi`` for example in /var/www - - :: - - sudo cp files/fedora-elections.wsgi /var/www - - Adjust the apache configuration file to point to it - - Adjust the wsgi file installed in /var/www to point to fedora_elections - - - Place the fedora-elections configuration file in - ``/etc/fedora-elections/fedora-elections.cfg`` - - :: - - sudo mkdir -p /etc/fedora-elections/ - sudo cp files/fedora-elections.cfg /etc/fedora-elections/ - - Restart apache: - - sudo /etc/init.d/httpd restart - -* How to contribute - -If you find bug or want to propose ideas or stuff to be implemented or if -you are interested to became a developer for this project just -ask on #fedora-admin irc channel on irc.freenode.net or use our -web site https://fedorahosted.org/elections. - -* Licence - -fedora-elections is licenced under GPL v2.