PR#50: Update README for 2017 - elections

elections

#50 Update README for 2017

Merged 6 years ago by pingou. Opened 6 years ago by jflory7.

jflory7/elections change/pretty-and-accurate-readme into develop

Make the README great again

Justin W. Flory • 6 years ago

39a6e88

README.md

file added

+182

		`@@ -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.`

README.rst

file removed

-175

		`@@ -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.`

jflory7 commented 6 years ago

This commit updates the README to not only look nice and pretty, but also update a few things for 2017:

Add background to what Vagrant is
vagrant-sshfs is packaged in Fedora proper now, no more COPR
FedoraHosted.org is dead, long live Pagure
Link to more things instead of only saying more things
systemd is the new kid on the block
Improve formatting
Expand on how to contribute and where to say hello

jflory7 commented 6 years ago

@pingou It would also be cool to get a new version cut of the Elections app (of course, after this election). @ryanlerch did a lot of cool, pretty improvements and it would be cool to see these make it into the deployed application. :smile:

Let me know if there's anything I can do to help.