Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add GFM code highlighting #912

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add GFM code highlighting #912

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 104 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ World of USO is a quiz game framework. It has been used since 2007 as a support

On a Mint/Ubuntu/Fedora system run the install script:

./install.sh
```sh
./install.sh
```

During the installation you will be asked to enter an username and password for the administrative user. You will use those to do the first login into World of USO and use full privileges for administrative actions.

Expand All @@ -31,15 +33,21 @@ The following packages need to be installed:

On **Debian-based** systems run the command:

sudo apt-get install python2.7 python-pip python-django python-dev python-virtualenv libldap2-dev libsasl2-dev libssl-dev
```sh
sudo apt-get install python2.7 python-pip python-django python-dev python-virtualenv libldap2-dev libsasl2-dev libssl-dev
```

On **Fedora 22 or higher** systems run the command:

sudo dnf -y install python-pip python-django python-devel python-virtualenv openldap-devel libgsasl-devel openssl-devel
```sh
sudo dnf -y install python-pip python-django python-devel python-virtualenv openldap-devel libgsasl-devel openssl-devel
```

On **Fedora 21 or lower** systems run the command:

sudo yum -y install python-pip python-django python-devel python-virtualenv openldap-devel libgsasl-devel openssl-devel
```sh
sudo yum -y install python-pip python-django python-devel python-virtualenv openldap-devel libgsasl-devel openssl-devel
```

Optional packages (in case of MySQL support):
* mysql-server
Expand All @@ -53,90 +61,120 @@ Optional packages (in case of MySQL support):

2. Browse to the Git repository and activate the virtualenv:

cd $PATH_TO_WOUSO_REPOSITORY
virtualenv -p python2.7 sandbox
source sandbox/bin/activate
```sh
cd $PATH_TO_WOUSO_REPOSITORY
virtualenv -p python2.7 sandbox
source sandbox/bin/activate
```

`$PATH_TO_WOUSO_REPOSITORY` is the location of the clone of the WoUSO repository.
`$PATH_TO_WOUSO_REPOSITORY` is the location of the clone of the WoUSO repository.

You'll notice it works as you get a prompt update: the `(sandbox)` string is prefixed to the prompt. Something like:
You'll notice it works as you get a prompt update: the `(sandbox)` string is prefixed to the prompt. Something like:

(sandbox)wouso@wouso-dev:~/wouso.git$
```sh
(sandbox)wouso@wouso-dev:~/wouso.git$
```

In case you do something wrong in the virtualenv, you may exit it using
In case you do something wrong in the virtualenv, you may exit it using

deactivate
```sh
deactivate
```

and you may then remove the `sandbox` folder:
and you may then remove the `sandbox` folder:

rm -r sandbox
```sh
rm -r sandbox
```

3. Install pip requirements while in the `$PATH_TO_WOUSO_REPOSITORY` folder:

pip install -r requirements-pip
pip install -r requirements-extra
```sh
pip install -r requirements-pip
pip install -r requirements-extra
```

4. Install `django-piston` for WoUSO REST API (by hand, because of a [weird bug](https://bitbucket.org/jespern/django-piston/issue/173/attributeerror-module-object-has-no)):

curl 'https://pypi.python.org/packages/source/d/django-piston/django-piston-0.2.3.tar.gz' | tar xzf -
cd django-piston-0.2.3; python setup.py install
cd ..; rm -r django-piston-0.2.3
```sh
curl 'https://pypi.python.org/packages/source/d/django-piston/django-piston-0.2.3.tar.gz' | tar xzf -
cd django-piston-0.2.3; python setup.py install
cd ..; rm -r django-piston-0.2.3
```


5. Go to `wouso` subfolder, run everything from there:

cd wouso/
```sh
cd wouso/
```

6. Create initial settings. First make a copy of example settings:

cp settings.py.example settings.py
```sh
cp settings.py.example settings.py
```

and edit the new file (`settings.py`). You may want to update the `DATABASES` setting (see next step).
and edit the new file (`settings.py`). You may want to update the `DATABASES` setting (see next step).

7. (optional) In case you want to use a MySQL database, you must have the MySQL server and client packages installed. For MySQL support in Python you can use `pip`:

pip install MySQL-python

Create the database and use and use appropriate settings. For example, one would issue these commands in the MySQL client prompt to create a database:

create database wouso default character set utf8 default collate utf8_general_ci;
create user 'wouso'@'localhost' identified by 'some_pass';
grant all privileges on wouso.* to 'wouso'@'localhost';
flush privileges;

The appropriate database configuration in the `settings.py` file will then look like this:

DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'wouso',
'USER': 'wouso',
'PASSWORD': 'wouso',
'HOST': 'localhost',
'PORT': '',
}
}
```sh
pip install MySQL-python
```

Create the database and use and use appropriate settings. For example, one would issue these commands in the MySQL client prompt to create a database:

```sql
create database wouso default character set utf8 default collate utf8_general_ci;
create user 'wouso'@'localhost' identified by 'some_pass';
grant all privileges on wouso.* to 'wouso'@'localhost';
flush privileges;
```

The appropriate database configuration in the `settings.py` file will then look like this:

```py
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'wouso',
'USER': 'wouso',
'PASSWORD': 'wouso',
'HOST': 'localhost',
'PORT': '',
}
}
```

8. Create database tables and load initial data:

./manage.py wousoctl --setup
```sh
./manage.py wousoctl --setup
```

You will be asked to enter an username and password for the administrative user. You will use those to do the first login into World of USO and use full privileges for administrative actions.
You will be asked to enter an username and password for the administrative user. You will use those to do the first login into World of USO and use full privileges for administrative actions.

9. Run the server:

./manage.py runserver
```sh
./manage.py runserver
```

By default the server listens for connections on localhost port 8000. In case you want the server to listen on all interfaces, run
By default the server listens for connections on localhost port 8000. In case you want the server to listen on all interfaces, run

./manage.py runserver 0.0.0.0:8000
```sh
./manage.py runserver 0.0.0.0:8000
```

You can now point your browser to an URL such as `http://localhost:8000` or `http://<IP>:8000/` (where `<IP>` is the IP address of the host where you installed World of USO).
You can now point your browser to an URL such as `http://localhost:8000` or `http://<IP>:8000/` (where `<IP>` is the IP address of the host where you installed World of USO).


If you want to leave the virtualenv, run

deactivate
```sh
deactivate
```


### Development Virtual Machine
Expand All @@ -148,13 +186,17 @@ In case you run into issues when installing/configuring World of USO or you just

You may create a development environment using [Vagrant](http://www.vagrantup.com/). Make sure Vagrant is installed, then run

vagrant up
```sh
vagrant up
```

You can now find a deployed version of WoUSO at [http://localhost:8000](http://localhost:8000).

All code is shared with the VM, which you can access using

vagrant ssh
```sh
vagrant ssh
```

From there you can find the project files and interact with the django project as usual.
This also generated a superuser `admin:admin`.
Expand All @@ -164,18 +206,24 @@ This also generated a superuser `admin:admin`.

After pulling new code from server, while in sandbox mode, update the database schema by running the migration action:

./manage.py migrate
```sh
./manage.py migrate
```

In case of issues, you may need to update the pip packages, by running the commands below while in the repository:

pip install -r requirements-pip
pip install -r requirements-extra
```sh
pip install -r requirements-pip
pip install -r requirements-extra
```

## Troubleshooting

### TemplateDoesNotExist at /admin/index.html

rsync -a -v --ignore-existing src dst
```sh
rsync -a -v --ignore-existing src dst
```

Where:
* **`src`** is `/yourvirtualenv/django/` (i.e. `$PATH_TO_WOUSO_REPOSITORY/sandbox/django/`)
Expand Down