7.57 KB
Newer Older
# Go (URL Shortener)
Jean Michel Rouly's avatar
Jean Michel Rouly committed
2 3 4

A project of [GMU SRCT](

5 6 7 8
Go is a drop-in URL shortening service. It aims to provide an easily
branded service for institutions that wish to widely disseminate
information without unnecessarily outsourcing branding.

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
## Local Enviornment Setup

### Prerequisities & Required Packages
First, install python, pip, and git on your system.
* Python is the programming language used for Django, the web framework used by Go.
* 'Pip' is the python package manager.
* Git is the version control system used for SRCT projects.

Open a terminal and run the following command:

`$ sudo apt-get update`

This retrieves links to the most up-to-date and secure versions of your packages.

Next, with:

`$ sudo apt-get install python python-dev python-pip git libfreetype6-dev`
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159

you install python and git.

Now, we're going to clone down a copy of the Go codebase from, the SRCT code respository.

Configure your ssh keys by following the directions at

Now, on your computer, navigate to the directory in which you want to download the project (perhaps one called development/ or something similar), and run

`$ git clone`

Finally, install these packages from the standard repositories:

`$ sudo apt-get install libldap2-dev mysql-server mysql-client libmysqlclient-dev python-mysqldb libsasl2-dev libjpeg-dev `

If prompted to install additional required packages, install those as well.

When prompted to set your mysql password, it's advisable to set it as the same as your normal superuser password.

### The Virtual Enviornment
Virtual environments are used to keep separate project packages from the main computer, so you can use different versions of packages across different projects and ease deployment server setup.

It's often recommended to create a special directory to store all of your virtual environments together (ie. development/virtualenv/), though they can be placed wherever is most convienent.


`$ sudo pip install virtualenv`

to install virtualenv system-wide.

Then in your virtual environment directory run:

`$ virtualenv go`

to create your virtual environment.

Activate it by typing:

`$ source go/bin/activate`

If you ever need to exit your virtual environment, simply run:

`$ deactivate`

Now, the packages you need to install for Go are in in the top level of the project's directory structure(go/).


`$ pip install -r requirements.txt`

to install all of the packages needed for the project.

### Database Configuration
Go is configured for use with a mysql database.

Load up the mysql shell by running

`$ mysql -u root -p insert_password_here`

and putting in your mysql password.

Create the database by running:


You can choose a different name for your database if you desire.

Double check your database was created by running:


Though you can use an existing user to access this database, here's how to create a new user and give them the necessary permissions to your newly created database:

`> CREATE USER 'god'@'localhost' IDENTIFIED BY 'password';`

For local development, password strength is less important, but use a strong passphrase for deployment. You can choose a different username.


`> GRANT ALL ON go.* TO 'god'@'localhost';`

This allows your database user to create all the tables it needs on the bookshare database. (Each model in each app's is a separate table, and each attribute a column, and each instance a row.)


`> GRANT ALL ON test_go.* TO 'god'@'localhost'; FLUSH PRIVILEGES;`

 When running test cases, django creates a test database so your 'real' database doesn't get screwed up. This database is called 'test_' + whatever your normal database is named. Note that for permissions it doesn't matter that this database hasn't yet been created.

The .* is to grant access all tables in the database, and 'flush privileges' reloads privileges to ensure that your user is ready to go.

Exit the mysql shell by typing:

`> exit`

### Additional Setup
For a currently undetermined reason you will need to comment out line 55 of go/go/go/ to avoid the app from literally exploding:

`# hashids_counter = URL.objects.count()`

Now, to configure your newly created database with the project settings, and set up your project's cryptographic key, copy the in settings/ to Follow the comment instructions provided in each file to set your secret key and database info.

Also copy to You will need to set DEBUG mode to True in order to view more details when things go awry.

Change directory into go/go/ and run:

`$ python makemigrations`

to create the tables and rows and columns for your database. This command generates sql code based on your database models.

Then run:

`$ python migrate`

to execute that sql code and set up your database. Migrations also track how you've changed your models over the life of your database, which allows you to make changes to your tables without screwing up existing information.

Finally, run:

`$ python createsuperuser`

to create an admin account, using the same username and email as you'll access through CAS. This means your 'full' email address, for instance Your password will be handled through CAS, so you can just use 'password' here.

(If you accidentally skip this step, you can run python shell and edit your user from there. Select your user, and set .is_staff and .is_superuser to True, then save.)

You can now uncomment line 55 from, we have avoided nuclear armageddon.

Finally, within 'go/go' run:

`$ python runserver`

to start the site. Open your preferred web browser and navigate to to see the site!

In order to approve yourself to be an 'approved user' you must navigate to and log in. Once in the admin page go to "registered users", and create a new registered user in the top right. Be sure to use the same username and Full Name aas your main account and select "approved" in the bottom row.

Jean Michel Rouly's avatar
Jean Michel Rouly committed
## To Do
161 162 163 164 165 166 167 168 169 170 171 172
* qr codes on links view-- need to save the pictures somewhere, render
    inline as well as in different formats and sizes for download, and be
    deleted along with the links
* Update the user authentication system (ie. port it to CAS to play nicely
    with GMU)
* Update the user registration system. Make it more intuitive to first time
    users, also update the connection between registered users and actual
    user auth accounts on the database.
* Set up Piwik to work with Go.
* Update the documentation on Go to include a setup guide
* Update the interface to bootswatch, perhaps? Maybe the same stylesheet as
    is used on SRCTWeb. (ie. complete HTML overhaul)
Jean Michel Rouly's avatar
Jean Michel Rouly committed
* Remove all Mason-specific branding.
Daniel W Bond's avatar
Daniel W Bond committed

## Notes for Production

Jean Michel Rouly's avatar
Jean Michel Rouly committed
Jean Michel Rouly's avatar
Jean Michel Rouly committed

Jean Michel Rouly's avatar
Jean Michel Rouly committed
179 180
The settings file should already be configured acceptably. You may need to
add a different authentication backend or database engine.
Jean Michel Rouly's avatar
Jean Michel Rouly committed

Jean Michel Rouly's avatar
Jean Michel Rouly committed
### nginx / Apache

Jean Michel Rouly's avatar
Jean Michel Rouly committed
184 185
You must configure an outside web server to properly host the static file
required to run this Django app.
Jean Michel Rouly's avatar
Jean Michel Rouly committed

187 188 189 190 191 192 193
### Cron

In order to expire links, you need to set up a cron job to run the
expirelinks command regularly. A sample cron script is available in the
repository and is named go-cleanlinks.cron. Drop this in cron.hourly and
change the paths so that they point to the virtualenv activate script and
Jean Michel Rouly's avatar
Jean Michel Rouly committed
194 195 196 197

# Troubleshooting

If your CAPTCHA is messing up, try checking that your system has `libfreetype6-dev` installed. If not, install it and remove + reinstall `pillow` in your virtual environment.