== Django-phpBB3 ==
Django-phpBB3 provides the database models of a existing phpBB3 installation. This is usefull for all people who like to access the phpbb forum database from a django application. It's not a phpBB clone or a forum!
Django-phpBB3 has also a script for migrate a phpBB3 forum into a [[http://djangobb.org/|DjangoBB forum]]. See below.
Notes:
Warning: Write access to the original phpBB database is not tested, yet. So it's not guaranteed that changes trough the django admin will work with phpBB3! So, in the current state, you should only access 'read-only' to the origin phpBB3 data ;)
Patches are welcome! Please send pull requests.
== example projects ==
We add two example projects:
| [[https://github.com/jedie/django-phpBB3/tree/master/django_phpBB3_project|django_phpBB3_project]] | minimal project without extra depencies | [[https://github.com/jedie/django-phpBB3/tree/master/phpBB2DjangoBB_project|phpBB2DjangoBB_project]] | DjangoBB example project for use the phpBB2DjangoBB migration command
== setup ==
{{{
~$ virtualenv DjangoBB_env
~$ cd DjangoBB_env/
/DjangoBB_env$ source bin/activate
(DjangoBB_env)/DjangoBB_env$ pip install django-phpBB3 # Will also install Django
}}}
(If default python interpreter is <2.7: Use: {{{virtualenv -p python2.7 DjangoBB_env}}} - see below)
Or if you will use the most recent git version: {{{
(DjangoBB_env)~/DjangoBB_env$ pip install -e git+git://github.com/jedie/django-phpBB3.git#egg=django-phpBB3 }}}
If you would like to test/use the DjangoBB migration install this:
{{{
(DjangoBB_env)/DjangoBB_env$ pip install -e git+git://github.com/slav0nic/DjangoBB.git#egg=DjangoBB
(DjangoBB_env)/DjangoBB_env$ pip install Whoosh
}}}
Maybe you want my dev branch of DjangoBB (More info in [[https://github.com/jedie/DjangoBB/wiki|My DjangoBB github wiki page]]):
{{{
(DjangoBB_env)/DjangoBB_env$ pip install -e git+git://github.com/jedie/DjangoBB.git@dev#egg=DjangoBB
(DjangoBB_env)/DjangoBB_env$ pip install Whoosh
}}}
=== local_settings.py example === {{{
#PHPBB_TABLE_PREFIX = "phpbb_"
DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'. 'NAME': 'phpbb3', # Or path to database file if using sqlite3. 'USER': 'phpbb3', # Not used with sqlite3. 'PASSWORD': 'foo bar', # Not used with sqlite3. 'HOST': '', # Set to empty string for localhost. Not used with sqlite3. 'PORT': '', # Set to empty string for default. Not used with sqlite3. } }
PHPBB_ATTACHMENT_PATH = "/path/to/phpBB/files/" }}}
=== init database ===
If you will test the two example projects, you need to initialises the database, e.g.:
{{{
~$ cd DjangoBB_env/
/DjangoBB_env$ source bin/activate
(DjangoBB_env)/DjangoBB_env$ cd src/django-phpbb3/phpBB2DjangoBB_project
(DjangoBB_env).../phpBB2DjangoBB_project$ # create local_settings.py here, see above!
(DjangoBB_env).../phpBB2DjangoBB_project$ ./manage.py syncdb --all
(DjangoBB_env).../phpBB2DjangoBB_project$ ./manage.py migrate --fake
}}}
== test django-phpBB3 ==
We added a test project for easy start in: [[https://github.com/jedie/django-phpBB3/tree/master/django_phpBB3_project|/django_phpBB3_project/]]
Create a {{{local_settings.py}}} into {{{/django_phpBB3_project/}}} see example above.
You must initialises the database (see above).
You can startup a test server with, e.g: {{{ ./manage.py runserver --traceback --insecure }}}
== migrate a phpBB3 installation to DjangoBB ==
We add a example project for a phpBB3 migration in: [[https://github.com/jedie/django-phpBB3/tree/master/phpBB2DjangoBB_project|/phpBB2DjangoBB_project/]]
The migration from phpBB3 to DjangoBB is implement as a migration command here: [[https://github.com/jedie/django-phpBB3/blob/master/django_phpBB3/management/commands/phpbb2djangobb.py|/django_phpBB3/management/commands/phpbb2djangobb.py]]
To run the migration you can use the minimal {{{phpBB2DjangoBB}}} example project example. This project includes the DjangoBB forum app and django-phpBB3 app. Before start, you must install the dependencies!
You must create a {{{local_settings.py}}} into {{{/phpBB2DjangoBB_project/}}} see example above.
Before you start migration: You should check if database encoding settings are ok. To check, login and check in //admin / Django_phpBB3 / Posts// if non-ascii characters are ok.
Typical problem are: e.g. in default ubuntu/debian setup a mysql server will use {{{latin-1}}} ! So before you start, you should correct this. e.g.: {{{ ALTER DATABASE test DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci }}} Make a SQL Backup before doing anything!!!
Run the migration with {{{./manage.py phpbb2djangobb}}}, e.g:
{{{
~$ cd DjangoBB_env/
/DjangoBB_env$ source bin/activate
(DjangoBB_env)/DjangoBB_env$ cd src/django-phpbb3/phpBB2DjangoBB_project
(DjangoBB_env).../phpBB2DjangoBB_project$ ./manage.py phpbb2djangobb
}}}
=== after migration ===
Important: No phpBB forum permissions would be migrated, yet. So: Before you make a migrated Forum available to public, you must manually //hide// any //internal// forums, if exists! To limit a forum in DjangoBB, e.g.:
You must update the haystack search index with e.g.: {{{ (DjangoBB_env).../phpBB2DjangoBB_project$ ./manage.py update_index --verbosity=2 }}} more information: http://django-haystack.readthedocs.org/en/latest/management_commands.html
Depend on the used database you must reset sequences. {{{ Sequences are indexes used by some database engines to track the next available number for automatically incremented fields. }}} more info: https://docs.djangoproject.com/en/dev/ref/django-admin/#sqlsequencereset-appname-appname
=== options === ==== cleanup_users ====
Add {{{--cleanup_users=x}}} to setup which users are migrate, where x is a number:
| 0 | all users | 1 | users with email addresses (skip bots) | 2 | users with email and has a 'lastvisit' date (default) | 3 | email + lastvisit and has created at least one post
=== migration limitations ===
Things that would not be transfered, yet:
Handling missing features in DjangoBB:
TODO:
=== migration - notes ====
==== username ==== The migration script copied the phpBB username 1:1 and doesn't cleanup anything. The django forms for creating/change a user will only limit with: {{{Letters, digits and @/./+/-/_ only}}} But the model fields is a simple {{{CharField}}}. A nick will be accepted in login depend on the login form you use in your project.
==== password ==== We migrate the phpBB3 passwords and add a own password hasher. [[https://docs.djangoproject.com/en/1.4/topics/auth/#password-upgrading|Django upgrade the old password]] with the default hasher (PBKDF2) on the first login. For this, it's needed to add the phpBB3 password hasher to your settings, e.g.: {{{ PASSWORD_HASHERS = ( 'django.contrib.auth.hashers.PBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', 'django.contrib.auth.hashers.SHA1PasswordHasher', 'django.contrib.auth.hashers.MD5PasswordHasher', 'django.contrib.auth.hashers.CryptPasswordHasher', 'django_phpBB3.hashers.PhpBB3PasswordHasher', ) }}} more info: https://docs.djangoproject.com/en/1.4/topics/auth/#how-django-stores-passwords
=== migration - open questions ====
=== troubleshooting ===
==== HTMLParseError while post migration ==== Maybe you used a older Python Version than 2.7.3 In older versions the {{{HTMLParser}}} is not so robust as in 2.7.3 Maybe default Python interpreter is 2.6, but 2.7 is installed to, than try: {{{
~$ python --version # Default python Python 2.6.6 ~$ python2.7 --version # Try if 2.7 is available Python 2.7.3
~$ virtualenv -p python2.7 DjangoBB_env }}} Work-a-round if you can't create a virtualenv with a newer Python interpreter: set: {{{settings.DJANGOBB_SMILES_SUPPORT = False}}} More Information here: https://github.com/jedie/django-phpBB3/issues/14
==== UnicodeEncodeError in the terminal while running migration ==== Solution: You must set either your locale, or the PYTHONIOENCODING environment variable, according to your terminal's encoding — in most cases, utf-8. More info can be found [[https://github.com/jedie/django-phpBB3/issues/9#issuecomment-8494830|in the comment of issues 9]]
==== How to debug migration ====
We use python built-in pdb module for debug a migration traceback.
[[http://pypi.python.org/pypi/pudb|pudb]] is used, if installed. To install it, run e.g.:
{{{
~$ cd DjangoBB_env/
/DjangoBB_env$ source bin/activate
(DjangoBB_env)/DjangoBB_env$ pip install pudb
}}}
== phpBB3 links ==
Here some links for phpBB documentations:
The SQL schema files from phpBB can be found here:
== history
== Project links ==
| Homepage | https://github.com/jedie/django-phpBB3 | PyPi | http://pypi.python.org/pypi/django-phpBB3/
=== donation ===
=== contact ===
Come into the conversation, besides the github communication features:
| Forum | http://www.pylucid.org/en/forum/11/ | IRC | #pylucid on freenode.net (Yes, the PyLucid channel...) | webchat | http://webchat.freenode.net/?channels=pylucid