Development environment #

System requirements #

You need to have docker and docker-compose V2 installed on your system in order to correctly set up the development environment.

You can look here for complete instructions.

Optionally, to improve performance, you can also increase the maximum number of user files able to be watched for changes with inotify:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Getting Started #

The interactive development environment requires some familiarity of tmux.

To start it, clone penpot repository, and execute:

./manage.sh pull-devenv
./manage.sh run-devenv

This will do the following:

  1. Pull the latest devenv image from dockerhub.
  2. Start all the containers in the background.
  3. Attach the terminal to the devenv container and execute the tmux session.
  4. The tmux session automatically starts all the necessary services.

This is an incomplete list of devenv related subcommands found on manage.sh script:

./manage.sh build-devenv # builds the devenv docker image (called by run-devenv automatically when needed)
./manage.sh start-devenv # starts background running containers
./manage.sh run-devenv   # enters to new tmux session inside of one of the running containers
./manage.sh stop-devenv  # stops background running containers
./manage.sh drop-devenv  # removes all the containers, volumes and networks used by the devenv

Having the container running and tmux opened inside the container, you are free to execute commands and open as many shells as you want.

You can create a new shell just pressing the Ctr+b c shortcut. And Ctrl+b w for switch between windows, Ctrl+b & for kill the current window.

For more info: https://tmuxcheatsheet.com/

It may take a minute or so, but once all of the services have started, you can connect to penpot by browsing to http://localhost:3449 .

Frontend #

The frontend build process is located on the tmux window 0 and window 1. On the window 0 we have the gulp process responsible of watching and building styles, fonts, icon-spreads and templates.

On the window 1 we can found the shadow-cljs process that is responsible on watch and build frontend clojurescript code.

Additionally to the watch process you probably want to be able open a REPL process on the frontend application, for this case you can split the window and execute this:

npx shadow-cljs cljs-repl main

Exporter #

The exporter build process is located in the window 2 and in the same way as frontend application, it is built and watched using shadow-cljs.

The main difference is that exporter will be executed in a nodejs, on the server side instead of browser.

The window is split into two slices. The top slice shows the build process and on the bottom slice has a shell ready to execute the generated bundle.

You can start the exporter process executing:

node target/app.js

This process does not start automatically.

Backend #

The backend related process is located in the tmux window 3, and you can go directly to it using ctrl+b 3 shortcut.

By default the backend will be started in a non-interactive mode for convenience but you can press Ctrl+c to exit and execute the following to start the repl:

./scripts/repl

On the REPL you have these helper functions:

  • (start): start all the environment
  • (stop): stops the environment
  • (restart): stops, reload and start again.

And many other that are defined in the dev/user.clj file.

If an exception is raised or an error occurs when code is reloaded, just use (repl/refresh-all) to finish loading the code correctly and then use (restart) again.

Email #

To test email sending, the devenv includes MailCatcher, a SMTP server that is used for develop. It does not send any mail outbounds. Instead, it stores them in memory and allows to browse them via a web interface similar to a webmail client. Simply navigate to:

http://localhost:1080