README.rst 5.5 KB
Newer Older
Jasper St. Pierre's avatar
Jasper St. Pierre committed
1 2 3 4 5
==============
SweetTooth-Web
==============

**SweetTooth-Web** is a Django-powered web application that, in co-operation
Yuri Konotopov's avatar
Yuri Konotopov committed
6
with some GNOME Shell integration helper (deprecated `NPAPI plugin`_ or `Browser extension`_)
Yuri Konotopov's avatar
Yuri Konotopov committed
7 8
allows users to install, upgrade and enable/disable their own Shell Extensions.
All operations with the Shell are done through a special helper which proxies
Yuri Konotopov's avatar
Yuri Konotopov committed
9
over to the Shell by DBus. Please note that `NPAPI plugin`_ is deprecated and was removed from GNOME Shell codebase.
Jasper St. Pierre's avatar
Jasper St. Pierre committed
10 11 12 13

Since extensions can be dangerous, all extensions uploaded to the repository
must go through code review and testing.

Yuri Konotopov's avatar
Yuri Konotopov committed
14
.. _NPAPI plugin: https://gitlab.gnome.org/GNOME/gnome-shell/tree/gnome-3-30/browser-plugin
15
.. _Browser extension: https://gitlab.gnome.org/GNOME/chrome-gnome-shell/
Jasper St. Pierre's avatar
Jasper St. Pierre committed
16

Oscar Domingo's avatar
Oscar Domingo committed
17 18 19
Requirements
------------

Yuri Konotopov's avatar
Yuri Konotopov committed
20 21 22 23 24 25

System Requirements:
  * `python`_ 3.6+
  * `xapian (xapian-core and xapian-bindings)`_

.. _python: https://www.python.org/
26
.. _xapian (xapian-core and xapian-bindings): https://www.xapian.org/
Yuri Konotopov's avatar
Yuri Konotopov committed
27

Oscar Domingo's avatar
Oscar Domingo committed
28 29 30 31 32
Python Requirements:
  * django_
  * django-autoslug_
  * django-registration_
  * pillow_
Yuri Konotopov's avatar
Yuri Konotopov committed
33
  * Pygments_
Oscar Domingo's avatar
Oscar Domingo committed
34

35
.. _django: https://www.djangoproject.com/
Oscar Domingo's avatar
Oscar Domingo committed
36
.. _django-autoslug: http://packages.python.org/django-autoslug/
37
.. _django-registration: https://pypi.org/project/django-registration
Oscar Domingo's avatar
Oscar Domingo committed
38
.. _pillow: https://github.com/python-pillow/Pillow
39
.. _Pygments: http://pygments.org/
Oscar Domingo's avatar
Oscar Domingo committed
40 41


42 43 44 45 46 47 48 49
Running with Docker
-------------------

Make sure you have both `Docker`_ and `Docker Compose`_ installed as well as runnning `Docker`_ instance.

You can start website with commands:
::

50
  $ git clone https://gitlab.gnome.org/Infrastructure/extensions-web.git
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
  $ cd extensions-web/openshift/docker
  $ MYSQL_USER=extensions-web \
    MYSQL_PASSWORD=SOME_PASSWORD \
    EGO_ALLOWED_HOST=* \
    EGO_DATABASE_URL=mysql://extensions-web:SOME_PASSWORD@db/extensions-web \
    EGO_NODE_ADDRESS=extensions-web \
    EGO_SECRET_KEY=SOME_SECRET_KEY \
    EGO_XAPIAN_DB=/extensions-web/data/xapian.db \
    docker-compose up --build

That's all! Website will be available as http://localhost:8080.

Don't forget to substitute "SOME_PASSWORD" and "SOME_SECRET_KEY" with proper values.

You also may want to create superuser account - look to virtualenv guide below for
apropriate command and `Docker`_ documentation for a way running command within running
`Docker`_ container.

.. _Docker: https://www.docker.com/
.. _Docker Compose: https://docs.docker.com/compose/


Running with virtualenv
-----------------------

76 77
You can get started developing the website with::

78
  $ git clone https://gitlab.gnome.org/Infrastructure/extensions-web.git
Yuri Konotopov's avatar
Yuri Konotopov committed
79
  $ cd extensions-web
Yuri Konotopov's avatar
Yuri Konotopov committed
80
  $ virtualenv --system-site-packages ./venv
81

82 83
I use `--system-site-packages` because we require Xapian, which doesn't have
its Python bindings in PyPI.
Yuri Konotopov's avatar
Yuri Konotopov committed
84 85 86 87 88
::

  $ . ./venv/bin/activate
  $ pip install -r ../requirements.txt

Oscar Domingo's avatar
Oscar Domingo committed
89 90 91
This will get all the needed PyPi packages in our virtual environment.

Create file "local_settings.py" (in the project root folder) and add the following settings:
Yuri Konotopov's avatar
Yuri Konotopov committed
92
::
93 94 95 96

  SECRET_KEY = 'super-random-secret-passphrase'
  ALLOWED_HOSTS = ['*']
  DEBUG = True
Yuri Konotopov's avatar
Yuri Konotopov committed
97

Oscar Domingo's avatar
Oscar Domingo committed
98 99
Once you've done that, proceed with the database migrations:
::
100

Yuri Konotopov's avatar
Yuri Konotopov committed
101
  $ python manage.py migrate
102
  $ python manage.py compilemessages
Oscar Domingo's avatar
Oscar Domingo committed
103
  $ python mange.py createsuperuser --username=joe --email=joe@email.com
Yuri Konotopov's avatar
Yuri Konotopov committed
104 105

After above steps your database should be initialized and almost ready to run.
Oscar Domingo's avatar
Oscar Domingo committed
106 107 108

You should manually specify your site's domain with SQL update:
::
Yuri Konotopov's avatar
Yuri Konotopov committed
109 110 111 112 113 114

  UPDATE `django_site`
  SET `domain` = 'your.domain.name',
      `name` = 'your.domain.name'
  WHERE `django_site`.`id` = 1;

Oscar Domingo's avatar
Oscar Domingo committed
115
And to start the webserver:
Yuri Konotopov's avatar
Yuri Konotopov committed
116 117 118
::

  $ python manage.py runserver
119

Yuri Konotopov's avatar
Yuri Konotopov committed
120
Log in using superuser account. You should be able to upload and review extensions.
121 122 123 124

.. _virtualenv: http://www.virtualenv.org/
.. _pip: http://www.pip-installer.org/

125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
Testing with the Shell
======================

If you have GNOME Shell, and you want to test the installation system, you're
going to have to hack your system. For security reasons, the browser plugin and
GNOME Shell both ping the URL https://extensions.gnome.org directly. The
easiest way to get around this is to make a development environment with the
proper things that it needs. Since the Django development server doesn't
natively support SSL connections, we need to install Apache. Follow the
instructions above to get a proper SweetTooth checkout, and then::

  # Install Apache
  $ sudo yum install httpd mod_wsgi mod_ssl

  # Generate a self-signed cert
140 141 142 143 144 145
  $ openssl req -new -nodes -out ego.csr -keyout extensions.gnome.org.key
  # Answer questions. The only one required is the Common Name. You must put
  # extensions.gnome.org -- the hostname -- as the answer.

  $ openssl x509 -req -in ego.csr -signkey extensions.gnome.org.key -out extensions.gnome.org.crt
  $ rm ego.csr
146
  $ chmod 600 extensions.gnome.org.key
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168

  # Install it on your system.
  $ sudo cp extensions.gnome.org.crt /etc/pki/tls/certs/
  $ sudo cp --preserve=mode extensions.gnome.org.key /etc/pki/tls/private/

  # The shell will look for a special file called 'extensions.gnome.org.crt',
  # for development purposes. Otherwise it will use your system's CA bundle.
  $ mkdir -p ~/.local/share/gnome-shell
  $ cp extensions.gnome.org.crt ~/.local/share/gnome-shell/

  # Configure Apache.
  $ cp etc/sweettooth.wsgi.example ./sweettooth.wsgi
  $ $EDITOR ./sweettooth.wsgi

  $ cp etc/sweettooth.httpd.conf.example ./sweettooth.httpd.conf
  $ $EDITOR ./sweettooth.httpd.conf
  $ sudo cp sweettooth.httpd.conf /etc/httpd/conf.d/sweettooth.conf

  # Edit /etc/hosts
  $ sudo tee -a /etc/hosts <<< 'extensions.gnome.org 127.0.0.1'