Skip to content

Install

Jump to bottom
Quivo edited this page Aug 21, 2018 · 18 revisions

Choose your desired install type:

Heroku Install

The fastest way to get fanarchive running is to deploy it to Heroku. To do that, click this neat little button:

Deploy

And either login to heroku so that it can spin up an app for you, or make a new heroku account. Once heroku has built the app and started it up for you, you should be able to navigate to https://your-app-name.herokuapp.com/ and see the archive's index page pop up.

Then, to properly secure your fanarchive install:

  1. Go to this django secret key generator site, and generate a new key.
  2. Copy the new key you just generated.
  3. Go to https://dashboard.heroku.com/apps/your-app-name/settings
  4. Scroll till you see "Config Variables", and then click on "Reveal Config Vars"
  5. Add a new variable with "SECRET_KEY" as the key, and then paste the new key you just generated into the "VALUE" field.
  6. Click the "Add" button to finish adding the variable.

Click here for further reading, or go back to top.

Local Install

Install Python

First, install Python 3.6 by following the appropriate tutorial from the Hitchhiker's Guide to Python's install page. If you have a package manager (e.g. Brew, Chocolatey) or have an IDE installed (e.g. one of the many versions of Visual Studio), or have already previously installed this version of Python, you may be able to skip this step.

How to check if Python is properly installed

To check if Python is installed properly, and has been added to your PATH:

  1. open Command Prompt (search for 'cmd' or 'command prompt' in the Start menu)
  2. type in python and hit enter
  3. python should tell you its version and offer you an interpreter prompt.
Optional: Setting up a virtual environment

If you want to use virtual environments to make it easier to work on this project, this is the time to set them up.

If you're on Windows, follow this tutorial, omitting the Flask-related stuff, and you should be all set.

NOTE: If you get a permissions error during the process e.g. trying to update pip, you need to run the command prompt as administrator (right-click on icon in start menu > Run as administrator).

If you're on Mac or Linux, you'll want to open up a Terminal/Bash prompt and do:

$ pip install virtualenvwrapper

If you get permissions errors trying that, then do:

$ sudo pip install virtualenvwrapper

Once virtualenvwrapper is installed, running workon will give you an empty list of virtual environments (because you haven't made any yet). To make a new environment, run:

$ mkvirtualenv env-name

And a new environment, env-name will be created and activated. To exit the environment, type deactivate and hit enter. To open the environment again, type workon env-name and hit enter.

To learn more about the virtualenvwrapper package, check out the docs for it here.

Install Git

First, you'll likely want to set up an account at GitHub if you don't already have one.

Next, if you don't already have Git installed, check out the Github tutorial for Setting up Git and follow along with the instructions for your platform.

Important Note: If you want to be able to contribute to fanarchive, make sure that your commit email address is one that you are comfortable having out on the internet. Note that you can use your Github-provieded no-reply email address as your commit email address.

Once you have Git installed, and your Git client of choice also downloaded (e.g. the official Github client, Sourcetree, etc), you'll want to sort out authentication. If this is your first time working with Git/Github, it is HIGHLY recommended to set up Git to use SSH authentication; it's fiddly and a bit of a daunting process, but it's a lot easier to scrub out old settings or switch to a new Github account while using SSH.

Clone fanarchive repo

If you're using a GUI Git client, you'll want to pull up their instructions for cloning repositories here. The fanarchive repo urls are below:

Protocol URL
SSH git@github.com:quivop/fanarchive.git
HTTPS https://github.com/quivop/fanarchive.git

To clone the repo using Git on the command line:

  1. Open Command Prompt, Terminal or Bash.
  2. (optional) enter workon project_name to start your virtual environment, if needed
  3. To clone the project into, say, your home directory:
    1. Type cd your\home\directory\path and hit enter.
      On Mac/Linux, that would be something like cd ~/.
      On Windows, it would be something like cd C:\Users\your_username\
    2. Type git clone <repo url> and hit enter.

By default, this will pull a copy of all files in the fanarchive repo to your local machine under home_directory\fanarchive.

Install fanarchive dependencies

To install the extra python packages needed to run fanarchive:

  1. (Optional) Start your virtual environment with workon project_name if you haven't already.
  2. In a command prompt (or bash prompt, or Terminal window), change to the directory you cloned the fanarchive repo into. E.g. ~\fanarchive, ~\projects\fanarchive, or whatever directory you used above.
  3. Type pip install -r requirements.txt and hit enter.

Edit environment variables

  1. Open the directory you cloned the fanarchive repo into.
  2. Open the file named .sample_env in your preferred text editor or IDE
  3. Edit the file according to the comments in it, and save it as .env

Now, when you run Django locally using runsslserver, your test server will automatically look in the .env file for certain important environment variables. All .env files are ignored by git in this project, so any variables you set there will not be pushed to the repo.

Take the archive for a spin

If you've got everything installed properly, you should be able to spin up the site using Django's test server, like so:

  1. Open Command Prompt, Bash or Terminal

  2. Change to the directory you cloned the fanarchive repository into. Examples:

    • Mac/Linux: cd ~\fanarchive
    • Windows: cd C:\Users\your_username\fanarchive

  3. Type python manage.py runsslserver and hit enter.

  4. The Django test server should end up saying something like:

    Django version 2.1.0, using settings 'archive.settings'
Starting development server at https://127.0.0.1:8000/
Quit the server with CONTROL-C.

  5. You can now navigate to https://127.0.0.1:8000/. You should see whatever default page fanarchive is currently set up to use.

Before you do any testing or make changes to the archive software, you will likely want to make sure your local db is set up properly. To do that, simply:

  • Open up Command Prompt again
  • Change to your local clone of the repo
  • cd archive and hit enter.
  • python manage.py migrate and hit enter. This will run all stored db migrations in $project_root\archive\fanarchive\migrations\, as well as elsewhere in the project.
  • python manage.py loaddata <fixture_name>, where <fixture_name> will be the current path to the current load of test data, which is currently stored in $project_root\archive\fanarchive\fixtures\.

Further reading

TBA

Clone this wiki locally