forked from saleor/saleor
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdevelopment.rst
155 lines (83 loc) · 4.31 KB
/
development.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
Development
===========
Working with templates
----------------------
Default storefront templates are based on `Bootstrap 4 <https://v4-alpha.getbootstrap.com/>`_.
You can find the files under ``/templates/``.
Working with front-end assets
-----------------------------
All static assets live in subdirectories of ``/saleor/static/``.
Stylesheets are written in `Sass <http://sass-lang.com/>`_ and rely on `postcss <http://postcss.org/>`_ and `autoprefixer <https://autoprefixer.github.io/>`_ for cross-browser compatibility.
JavaScript code is written according to the ES2015 standard and relies on `Babel <https://babeljs.io/>`_ for transpilation and browser-specific polyfills.
Everything is compiled together using `webpack module bundler <https://webpack.github.io/>`_.
The resulting files are written to ``/saleor/static/assets/`` and should not be edited manually.
During development it's very convenient to have webpack automatically track changes made locally.
This will also enable *source maps* that are extremely helpful when debugging.
To run webpack in *watch* mode run:
.. code-block:: bash
$ npm start
.. warning::
Files produced this way are not ready for production use.
To prepare static assets for deployment run:
.. code-block:: bash
$ npm run build-assets --production
Working with backend code
-------------------------
Python dependencies
~~~~~~~~~~~~~~~~~~~
To guarantee repeatable installations all project dependencies are managed using `pip-tools <https://github.com/nvie/pip-tools>`_.
Project's direct dependencies are listed in ``requirements.in`` and running :code:`pip-compile` generates ``requirements.txt`` that has all versions pinned.
We recommend you use this workflow and keep ``requirements.txt`` under version control to make sure all computers and environments run exactly the same code.
Running tests
-------------
Before you make any permanent changes in the code you should make sure they do not break existing functionality.
The project currently contains very little front-end code so the test suite only covers backend code.
To run backend tests use `pytest <http://docs.pytest.org/en/latest/>`_:
.. code-block:: bash
$ py.test
You can also test against all supported versions of Django and Python.
This is usually only required if you want to contribute your changes back to Saleor.
To do so you can use `Tox <https://tox.readthedocs.io/en/latest/>`_:
.. code-block:: bash
$ tox
Continuous integration
----------------------
The storefront ships with a working `CircleCI <https://circleci.com/>`_ configuration file.
To use it log into your CircleCI account and enable your repository.
.. _docker_dev:
Docker
------
Using Docker to build software allows you to run and test code without having to worry about external dependencies such as cache servers and databases.
.. warning::
The following setup is only meant for local development.
See :ref:`docker_deployment` for production use of Docker.
Local prerequisites
*******************
You will need to install Docker and
`docker-compose <https://docs.docker.com/compose/install/>`_ before
performing the following steps.
To build assets you will need `node <https://nodejs.org/en/download/package-manager/>`_ and `webpack module bundler <https://webpack.github.io/>`_.
.. note::
Our configuration exposes PostgreSQL, Redis and Elasticsearch ports. If you have problems running this docker file because of port conflicts, you can remove 'ports' section from docker-compose.yml
Usage
*****
1. Install JavaScript dependencies
.. code-block:: bash
$ npm install
2. Prepare static assets
.. code-block:: bash
$ npm run build-assets
3. Build the containers using ``docker-compose``
.. code-block:: bash
$ docker-compose build
4. Prepare the database
.. code-block:: bash
$ docker-compose run web python manage.py migrate
$ docker-compose run web python manage.py collectstatic
$ docker-compose run web python manage.py populatedb --createsuperuser
The ``--createsuperuser`` switch creates an admin account for
``[email protected]`` with the password set to ``admin``.
5. Run the containers
.. code-block:: bash
$ docker-compose up
By default, the application is started in debug mode, will automatically reload code and is configured to listen on port ``8000``.