Text of docs.tildes.net › development › general-development as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

General Development Info

Tildes Docs Development General Development Info Page last updated: April 18, 2021 ( view history ) Contents Vagrant Changing the Vagrant box's resources SSHing into the VM Shared folders with the VM Keeping your dev version up-to-date Overall language/framework/server General development/debugging Interactive shell Adding new Python packages/libraries HTML templates and CSS Javascript, AJAX and the "web API" Database Interacting with the database in the app Making changes to the database tables Data validation/sanitization Instrumentation and metrics Running checks on your code Testing Type-checking with mypy Note: This page is fairly scattered overall and should be split up into multiple pages in the future.

The goal is mostly to have a lot of information that developers might find useful so that they, at least, have a starting point to find out more about how something works. If you haven't already, follow the instructions on the Development Setup page to get a development version running on your local machine. Vagrant In general, you shouldn't need to do very much with Vagrant directly, but there are a few commands you should know: vagrant up - Run this to boot the VM (or create a new one).

It will probably take a few minutes to finish. vagrant ssh - Open an SSH session into the VM. You will, probably, want to have one of these open almost all the time while developing to be able to run checks, look at the database, etc. vagrant provision - If you make any changes to the Salt states, run this to re-apply everything to the VM and make sure its state matches the expected one vagrant halt - Shut down the VM. vagrant destroy - This will completely destroy the VM, and next time you run vagrant up it will re-build it from scratch.

If your dev environment ever ends up broken, it's usually simplest to just destroy/recreate like this. Changing the Vagrant box's resources This generally shouldn't be necessary, but it's possible to change the resources the Vagrant box has access to by editing the Vagrantfile in the base directory. By default, the box is set up with 4GB of RAM and 4 CPUs, but you can adjust these by editing these two lines near the bottom of the file: vb . memory = "4096" vb . cpus = "4" Important - if you edit those lines : Do not set the memory lower than 2048 (2GB).

The VM will almost certainly end up swapping itself to death if it has less memory than that. If you change the values, run git update-index --assume-unchanged Vagrantfile so that git ignores those changes to the file and won't always want to commit them along with any actual updates you make to the Tildes code. SSHing into the VM You can open an SSH session into the VM by running vagrant ssh . Once inside, the application's virtual environment (venv) should automatically be activated for you, and you should be in the base application directory ( /opt/tildes/ ).

Unless otherwise stated, all commands mentioned in this page should be assumed as needing to be run from inside the VM, from the directory /opt/tildes/ , with the venv activated. Shared folders with the VM Vagrant maintains a few shared folders with the VM, which means that any changes you make to files in these folders from outside will be available inside the VM immediately. This allows you to edit the code from your main OS and have those changes reflected by your dev site that is being served from the VM.

Warning: This sharing is bi-directional, so any changes made in these folders inside the VM will also affect the folders outside. Take care not to delete or change files in the shared folders inside the VM unless you want those changes to affect the "real" version of the file outside. The following folders are shared (defined in the Vagrantfile ): Outside folder Path inside VM <base>/tildes/ /opt/tildes/ <base>/salt/salt/ /srv/salt/ <base>/salt/pillar/ /srv/pillar/ Keeping your dev version up-to-date First of all, it's definitely easiest if you keep your master branch "clean" by always working on all changes in their own branch .

Assuming you're working that way and have the official repo set up as a remote named "upstream" ( similar to the setup in this guide ), you can update to the latest code by running (from your own machine, NOT the Vagrant VM): git checkout master git pull upstream master After the pull completes, you may need to run additional commands depending on what exactly was updated. These commands are safe, so it should always be fine to just run them anyway if you're not sure: If there were any changes to files in the salt/ directory, you should re-apply the Salt states to your Vagrant VM by running (from your own machine, while the Vagrant VM is running) vagrant provision .

If there are any new files in the tildes/alembic/versions/ directory, you will need to run (from inside the VM) alembic upgrade head . As always, if something goes wrong and your dev VM ends up in a broken state, you can just destroy and recreate it and everything should be functional again. All your code changes, branches, etc. will be safe, as long you didn't make any changes directly inside the VM (which you usually shouldn't be doing anyway).

You should also try to update your branch(es) to use the latest code as soon as possible (and definitely before submitting a merge request), which should usually be as simple as, for each branch (again, on your own machine): git checkout my-branch-name git rebase master Overall language/framework/server The application is written in Python 3.8 , using the Pyramid web framework . It is served by Gunicorn behind an nginx reverse-proxy.

General development/debugging The development version is set up to automatically restart when any changes are detected to the code, so it should not be necessary to do anything manually to have changes take effect. It is running in debug mode, which will mean that any Python errors encountered should be displayed in the browser including a full traceback, ability to open an interactive shell in-browser and inspect variables, and so on.

The Pyramid debug toolbar is enabled and accessible on any page by clicking the red Pyramid icon on the right edge. The debug toolbar interface allows you to see various information about each request, such as examining properties of the request, and checking which database queries were executed (and how long they each took). If you introduce a "lower-level" error such as a Python syntax error, the application will fail when it attempts to restart and you won't be able to access the usual debugging methods.

This usually appears as a "502 Bad Gateway" error in the browser. To see the details of the error preventing Gunicorn from starting, you will need to run sudo journalctl -u gunicorn.service -f , which should display the traceback. Gunicorn is set up to automatically try restarting every 30 seconds, so after fixing the error you shouldn't need to do anything except wait (up to) 30 seconds for it to restart. However, you can always restart it immediately by running sudo systemctl restart gunicorn.socket .

Interactive shell You can open an interactive IPython shell inside the app environment by running invoke shell . This will include a request object that you can use to make database changes via request.db_session , just as inside app code. Note that any database changes will need to be manually committed by calling request.tm.commit() . Adding new Python packages/libraries If you need to add a new Python dependency, you need to update a few files that define which dependencies the app installs.

The list of the packages that need to be installed to run Tildes is kept in requirements.in , while the list of packages needed for a development version is in requirements-dev.in (which includes requirements.in ). These files are used to generate requirements.txt and requirements-dev.txt , which are snapshots of the individual packages (including all dependencies) and the versions that are currently being used. To install a new

The rest of this page is on the live site.