To run Palanaeum on your local machine for development purposes you need to set up a virtual machine. That's super easy to do on Linux
Download and install:
- VirtualBox: https://www.virtualbox.org/wiki/Downloads
- Vagrant: https://www.vagrantup.com/downloads.html
- If you're on Windows you need to have an ssh client installed, I suggest
- Install git from: https://git-scm.com/download/win
- Add C:\Program Files\Git\usr\bin to your PATH system variable (this can be done by selecting "Use Git and optional Unix tools from the Windows Command Prompt" during Git installation).
- Check if typing
sshin your console works. If it does, reboot your machine to make sure everything works fine and proceed.
In your console, go to main palanaeum directory:
cd <path to palanaeum>
Start up Vagrant virtual machine:
This step will take some time to complete. When you first start a vagrant box, it has to download a system image (couple hundreds MB) and install all required software in this system (another hundred MBs to donwload). Starting the system next time, will be faster though, as the state of the machine is not forgotten until you destroy it.
Once the machine is up and you're back in control of your console window, you can SSH into newly created virtual machine:
Go to the directory where Palanaeum project is mapped:
Create a superuser account (this should be done only once, when you first run the machine):
python3 manage.py createsuperuser
And start up a django development server:
python3 manage.py runserver_plus
Now you can get to work with Palanaeum! It's available from you host machine under this address:
Any changes you make to Palanaeum project files are automatically included in the virtual machine, so you can see the results of your work instantaneously! :)
Note: Audio playback isn't working 100% correctly on the Django dev server. It doesn't support skipping to selected part of the audio file, so you'll have to believe me that this functionality will work on a proper Nginx server ;)
Now, when you're done with working with Palanaeum, remember to exit the virtual machine and call:
to turn it off. Otherwise, it will continue to block resources on your computer until you reboot. To start working on Palanaeum again, just follow the instructions starting with step 2.
To be able to process uploaded files, you need to have a Celery process running in the background on the virtual machine. This can be achieved in many ways, one of which is to:
Start up a new terminal window
Log into the virtual machine using
Starting the the Celery worker process:
cd /vagrant celery worker -A palanaeum
Leave it working as long as you work with Palanaeum.
Updating the sources
From time to time you'll need to pull new changes made by others. This may include changes in requirements and in database structure. To keep all dependencies updated, here's what you should do after pulling the newest sources from repository.
# This code should be executed inside the VM cd /vagrant sudo pip3 install -Ur requirements.txt python3 manage.py migrate
This way, all necessary libraries should be installed and database structure should be updated. If this fails, you can always fall back to:
# This should be executed on the host machine vagrant destroy vagrant up
Setting up Sites module
Edit Site objects in database, to set proper domain name and site name.
Generating API keys
If you want to allow unlimited access to API for someone, you need to create an authentication token for them:
./manage.py drf_create_token <username>
This token should be added to HTTP requests inside a header:
Authorization: Token put_your_token_here