Branch: refs/heads/master Author: Enrico Tröger enrico.troeger@uvena.de Committer: Enrico Tröger enrico.troeger@uvena.de Date: Tue, 14 May 2013 22:20:07 UTC Commit: ae6b36443dd5d8cc7e3963416a7bd49798c0cd55 https://github.com/geany/www.geany.org/commit/ae6b36443dd5d8cc7e3963416a7bd4...

Log Message: ----------- Add first version of development environment howto

To be continued, made with Geany and the great Markdown plugin.

Modified Paths: -------------- README.dev.md

Modified: README.dev.md 184 files changed, 184 insertions(+), 0 deletions(-) =================================================================== @@ -0,0 +1,184 @@ +www.geany.org - Dev Environment +=============================== + +About +----- +This document describes the process of setting up a development environment to +get a local instance of this website running. + +The website is implemented as a Django (https://www.djangoproject.com/) project +and uses Mezzanine (http://mezzanine.jupo.org/) for content management. + +As Django is based on Python, first of all you need Python and a couple of +extra packages installed on your system. + +For now, the code is tested against Python2 only. + + +Prepare your system +------------------- + +To ease package handling and to get a clean environment, we use +virtualenv. Into the virtualenv we will install Django, Mezzanine and a couple of +other helper packages. + +To be able to use virtualenv, you first need to install it as well as some +development libraries for the MySQL and Memcache client libraries. +The most easy way is to use the package manager of your distribution. +On the Debian like systems the following command should install the necessary +packages: + + apt-get install python-virtualenv python-pip libmysqlclient-dev libmemcached-dev + + +Get the code +------------ + +Perform a usual clone of the www.geany.org repository from Github: + + git clone git://github.com/geany/www.geany.org + + +Setting up a virtualenv +----------------------- + +Change into the freshly cloned repository directory and execute the following commands +to create a new virtualenv and install required Python packages: + + export PIP_REQUIRE_VIRTUALENV=true + export VIRTUALENV_USE_DISTRIBUTE=true + export VIRTUALENV_NO_SITE_PACKAGES=true + + virtualenv --distribute --no-site-packages venv + # activate virtual environment + source venv/bin/activate + # upgrade some packages, just to be safe + pip install --upgrade pip distribute + # very helpful tool to manage packages in addition to pip + pip install yolk + # install our requirements + pip install -r requirements.txt + +This will setup a new virtualenv, upgrade the Python package manager +pip and install required packages for the website. + + +Create a local config +--------------------- + +Use a text editor of choice (we all know what this would be...) and create a new file +*local_settings.py* in *www.geany.org/geany/* (next to the existing *settings.py*). + +Django will first read *settings.py* and then overwrite all settings found in +*local_settings.py*. This way you can adjust the installation to your needs. +Also, some sensitive settings like the database connection are not properly +configured in *settings.py* on purpose, so you **must** configure them +locally. + +You can use the following sample *local_settings.py* as a start and then adjust +the settings to your needs: + + DEBUG = True + + DATABASES = { + "default": { + "ENGINE": "django.db.backends.mysql", + "NAME": "dbname", + "USER": "dbuser", + "PASSWORD": "supersecret", + "HOST": "127.0.0.1", + }, + 'nightlybuilds': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'dbname2', + "USER": "dbuser", + "PASSWORD": "supersecret", + "HOST": "127.0.0.1", + } + } + + # some random characters, should be unique per site, e.g. use str(uuid.uuid4()) + SECRET_KEY = "12345" + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache', + } + } + + NIGHTLYBUILDS_BASE_DIR = '/path/to/nightlybuilds/or/just/empty/' + + +### Database settings ### + +The above example configures a MySQL database connection. +For local development you can also use Sqlite which is simpler +to setup but harder to work with when you need to manipulate the +data directly. +Your choice. +Whatever database you use, ask Enrico to get a dump of a demo database +to get something to work with. This dump can be easily imported into +a configured database with the following command: + + python manage.py loaddata geany_dump.fixture + + +Start the development server +---------------------------- + +After you setup everything as described above, you are almost ready +to start the development server to actually do something. + +Before, just one further step is required: activate your virtual environment. +Execute the following command in the directory *www.geany.org*: + + source venv/bin/activate + +This will activate the previously created virtualenv and mangles +your Python environment so that the interpreter and related packages +in the *venv* sub directory are used instead of the gloablly installed +ones. +On some shells, you will see a `(venv)` prefix in the prompt indicating +a virtualenv is activated. +If you later want to clean up your shell and leave that virtualenv, just +type `deactivate` in your shell. + +Now, finally, it's time to start your development server: + + python manage.py runserver + +This will start a simple HTTP server on *localhost* port 8000. +You can open the resulting site in your browser by pointing it +to *http://localhost:8000*. + +Basically now you are done and you can start improving the website. +A little detail you might notice: once you change any .py file +which is knwon by Django, the development server will restart automatically +to reload the changed file(s). This is very helpful. + +To stop the server, simply interrupt it with *Ctrl-C*. + + +Special hostnames / DNS +----------------------- + +Since this website project not only contains www.geany.org but also +some related subsites (pastebin.geany.org, nightly.geany.org) there is +a special DNS record on the geany.org zone: ***.local.geany.org**. + +This record and all subdomains will resolve to *127.0.0.1* (aka *localhost*). + +In your browser you can use http://pastebin.local.geany.org/ and +http://nightly.local.geany.org/ to use this subsites with your +local development server. +All other domains not recognized as a known subsite will fallback to +the main website. + + +Useful shell aliases +-------------------- + +No magic, just save some typing: + + alias vac='source venv/bin/activate' + alias runserver='python manage.py runserver'

-------------- This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).