|project status||build status||more info|
Getting started (with docker)
in a shell:
# install docker docker pull quay.io/liqd/aula git clone --recursive https://github.com/liqd/aula cd aula ./docker/run.sh # now you are inside the container. stack install --fast --allow-different-user aula
Now, to have a quick look at the pages, do
then point your browser to localhost:8080
Note: when you want to
git pull, do this outside of docker,
git clone was performed outside. Otherwise, paths may be wrong.
Getting started (without docker, without stack)
https://github.com/hspec/sensei is a tool for rapid re-compilation and testing. If you want to use it, follow these steps:
- install any required system and ghc packages, e.g., for Debian-based systems, those mentioned in https://github.com/liqd/aula-docker/blob/master/Dockerfile in particular, libpq-dev and zlib1g-dev
- in a shell:
git clone --recursive https://github.com/liqd/aula export AULA_ROOT_PATH=`pwd`/aula cd aula cabal sandbox init
Now, to have a quick look at the pages, do
make aula-server make content # (in another terminal)
The second line generates some demo content, but also the initial user without which you can't login and create more users.
Now point your browser to localhost:8080
Using sensei for file-watch testing during development (with docker)
To start sensei, open a new terminal window and do this:
./docker/run.sh # now you are inside the container. make sensei
This will watch your files, and if anything changes, re-compile and run the test suite.
If you are already running a docker container in another terminal, but want to keep that terminal open to do other things, you can connect to that container with a new shell:
./docker/run.sh --connect # now you are inside the container. make sensei
You can use seito (same git repo, different executable) to pull the last error report into your IDE to get pointed to the source code locations.
In demo mode, the aula footer contains a link "create sample page" that points you to a text page that contains the data describing the status of the web page you are looking at.
If you cut&paste this value into a file, and move it to
$HOME/aula-samples, you can use the following process to work on the
ToHtml instance of that page in real-time, having instantaneous
refresh on your changes. This is also valuable if you want to report
an issue with the contents of a page.
Again, start the server like above, but this time make sure that outside of the docker container, you have $AULA_SAMPLES defined:
export AULA_SAMPLES=$HOME/aula-samples/ ./docker/run.sh # do not use --connect here! # now you are inside the container. make aula-server
$AULA_SAMPLES directory shouldn't be inside the
If it is, a sensei re-run will be triggered by its own
changes to the html files, resulting in a very noisy loop.
NOTE: docker has a VOLUME under
allows you to edit the html code from outside of docker, and still
serve it from the inside. If you set $AULA_SAMPLES to a directory of
your choice outside docker, and to
/root/html-templates inside, the script ./docker/run.sh will mount the outside directory into the
NOTE: This only works if you do not call
--connect. (If you have a docker container running elsewhere,
consider shutting it down first, and later connecting to the one
To refresh the HTML from the same content (same texts and everything), open a new terminal window and do this:
./docker/run.sh --connect make click-dummies-refresh
The html pages are created in
$AULA_SAMPLES/, and can be browsed
http://localhost:8080/samples/. You can do two things now:
Edit the html pages directly. If you want to keep or diff your changes, you can initialize a local git repo (
cd $AULA_SAMPLES && git init) and commit them there.
Edit source code in the original repo under
src/Frontend/Page/*.hs. If you do this,
$AULA_SAMPLES/*.htmlwill be overwritten, so make sure that all valuable changes you make there are under git control and recorded apropriately.
You can combine the two work-flows and edit first the html, then record, then edit the Haskell source code and use git to diff the generated html against the html you tweaked manually.
click-dummies-refresh go into a loop, so you
need two terminals. If you have two displays, you can move your
browser and the terminal with the refresh loop to one, and your source
code editor to the other. The browser will auto-refresh at any modification
and you will never have to focus there, no matter whether you
work on the haskell sources or on the html.
For more info on this, check out
SASS is used for styling, use the following command to compile the SASS to CSS
You need the sass compiler installed http://sass-lang.com/install
sass --watch static-src/scss/imports.scss:static/css/all.css --style compressed
... or just run it once:
sass static-src/scss/imports.scss:static/css/all.css --style compressed
You need fontcustom installed https://github.com/FontCustom/fontcustom
- Add your SVGs to static-src/icons-svg/ No strokes, fills only.
fontcustom compile -c ./fontcustom.yml