{"id":26766172,"url":"https://github.com/ucl/frrant","last_synced_at":"2026-06-30T02:31:14.964Z","repository":{"id":37737190,"uuid":"312338365","full_name":"UCL/frrant","owner":"UCL","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-25T21:23:40.000Z","size":8805,"stargazers_count":2,"open_issues_count":36,"forks_count":0,"subscribers_count":3,"default_branch":"development","last_synced_at":"2026-06-25T23:10:39.938Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UCL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-11-12T16:47:28.000Z","updated_at":"2026-06-17T11:50:08.000Z","dependencies_parsed_at":"2024-02-19T13:26:56.000Z","dependency_job_id":"3af3e190-c99b-40f9-9886-9082173d55c1","html_url":"https://github.com/UCL/frrant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UCL/frrant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2Ffrrant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2Ffrrant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2Ffrrant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2Ffrrant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UCL","download_url":"https://codeload.github.com/UCL/frrant/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2Ffrrant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34950328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-28T20:19:22.737Z","updated_at":"2026-06-30T02:31:14.936Z","avatar_url":"https://github.com/UCL.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Fragments of the Roman Republican Antiquarians\n\nResearch management platform for the Fragments of the Roman Republican Antiquarians grant.\n\n# Documentation\n\nHigh level design: https://wiki.ucl.ac.uk/display/IA/Republican+Antiquarian+HLD\n\n# License\n\nUnless otherwise noted, everything in this repo is licensed under GPL3. Details are in [LICENSE.txt](./LICENSE.txt).\n\n# Development\n\n## Branches\n\n* `production` holds production code installed in the production server.\n* Feature branches are named `feature/\u003cbranch_name\u003e`, and contain work in progress that will be merged onto the `development` branch via approved pull requests.\n* Bug fix branches are named `fix/\u003cbranch_name\u003e`\n\n## Running locally\n\nThis project uses containers. Below are set up instructions and useful commands.\n\n### 1. Install Docker Engine\n\n- Follow the instructions here for your platform: https://docs.docker.com/get-docker/\n- You don't need Docker Desktop necessarily, the command line tool is sufficient.\n\n### 2. Checkout the RARD source code\n\n- Create a working folder, e.g. `~/projects/` and `cd` into it\n\n- Clone the repo\n\n```git clone git@github.com:UCL/frrant.git```\n\n- Checkout the development branch:\n\n```git checkout development```\n\n### 3. Build the containers\n\n- For the example project location above:\n\n```cd ~/projects/frrant/src```\n\nNote that for running locally (on our own machines) we use the `local.yml` config and not `production.yml` which is for deployment to the production platform.\n\n```docker compose -f local.yml build```\n\n(or `docker-compose` for older versions of Docker) to ensure everything is built from scratch, you can add `--no-cache`\n\n```docker compose -f local.yml build --no-cache```\n\n- Bring up the project\n\n```docker compose -f local.yml up```\n\nor as a background process:\n\n```docker compose -f local.yml up -d```\n\nNB the output will be hidden when run in the background. To inspect the logs after the fact:\n\n```docker compose -f local.yml logs -f```\n\n(the `-f` will update the output as more log messages come in. Omit `-f` to just see a snapshot).\n\n- With the container running, browse to `localhost:8000` in your browser and you should see the project's home page.\n\nTo restart the project, e.g. if some changes have been made to code that don't need the container to be rebuilt then use:\n\n```docker compose -f local.yml down```\n\n```docker compose -f local.yml up```\n\nIf any changes are made to the machine configuration, e.g. new pip packages installed, then the project will need to be rebuilt. Safest is to rebuild with no cache (see above) though this will take longer. Depending on the change it might be advisable to try rebuilding first without the `--no-cache` option to save time.\n\n```docker compose -f local.yml down```\n\n```docker compose -f local.yml build [--no-cache]```\n\n```docker compose -f local.yml up```\n\n### 4. User Accounts\n\nUser accounts are created by the superuser. For convenience, and *on local development containers only* a superuser account is automatically created when the container is built.\n\nLog into the admin area `localhost:8000/admin` using username: `developer` password: `developer`\n\nCreate users in the standard Django admin.\n\nLog out of the admin and navigate to `localhost:8000` and follow the links to log in with the credentials you entered.\n\n### 5. Useful Docker commands\n\nCommands (shell or Django commands etc) are run on the Docker container via `docker compose` using the local configuration.\n\nYour container needs to be running while these commands are run.\n\n#### To stop the containers:\n\n```docker compose -f local.yml down```\n\n#### To stop the containers and remove the volumes\n\nThe `-v` option will delete any volume data e.g. Postgres data\n\n```docker compose -f local.yml down -v```\n\n#### Open a Django shell:\n\nA couple of useful shell scripts, `manage` (for Linux and Mac) and `manage.bat` (for Windows)\nhave been provided in the `src` directory.\nThese can be used like the standard `manage.py` script provided by Django,\nbut inside the local Docker compose network.\n\nSo, from the `src` directory, on Linux or Mac you can run:\n\n```./manage shell```\n\nOr at a Windows command prompt equivalently:\n\n```manage.bat shell```\n\n### Open a PostgreSQL shell in local:\n\n```docker compose -f local.yml exec postgres psql -d rard -U ftTUlBrLLgvsMhazNCenkVazbscHpykq```\ne.g.:\n- List all databases: \\l\n- View all tables in the current database: \\d\n- Describe a table: \\d table_name\n- Quit psql: \\q\n\n#### Run a general Django management command:\n\n(for example `createsuperuser`)\n\n```./manage \u003ccommand\u003e [arguments]```\n\n(or `manage.bat` on Windows)\n\n### 6. Running Tests:\n\n#### Run unit tests:\n\nNote that by adding `--rm` to the commands then the container in which the tests are run is deleted once the tests have finished.\n\n```docker compose -f local.yml run --rm django pytest```\n\n#### Run unit tests with coverage:\n\n```docker compose -f local.yml run --rm django coverage run -m pytest```\n\nNB to view coverage results,\n\n```docker compose -f local.yml run --rm django coverage report```\n\nwhich prints a top-level summary to the console. Alternatively for more detail, run\n\n```docker compose -f local.yml run --rm django coverage html```\n\nwhich creates a local folder `htmlcov`. Browse to the file `index.html` in that folder\n\nto run just one file e.g.:\n\n```docker compose -f local.yml run --rm django coverage run -m pytest -v ./rard/research/tests/views/test_bibliography.py```\n\nor just run the failing test or test class (marked with @pytest.mark.failingtest):\n\n```docker compose -f local.yml run --rm django coverage run -m pytest -m failingtest```\n\n#### Check all of the below together:\n\n```\ngit add .\npre-commit\n```\n\nif you get a red Fail message, run both lines again until there are no Fails\n\n#### Check code comprehensively:\n\n```docker compose -f local.yml run --rm django flake8```\n\n(no errors means check passed)\n\n#### Check code style only:\n\n```docker compose -f local.yml run --rm django pycodestyle```\n\n(no errors means style check passed)\n\n#### Check object types:\n\n```docker compose -f local.yml run --rm django mypy rard```\n\n#### Fix import order:\n\nThe command below will correct the order of your python imports to meet the standard\n\n```docker compose -f local.yml run --rm django isort .```\n\n(import order errors when running the flake8 command should be fixed automatically by running the above command)\n\n### 7. Django Migrations\n\nIf you make changes to model definitions (i.e. in the `models.py` files) then these need to be reflected in a migration file.\n\nA migration file is a Python 'patch' file generated by Django to apply the changes you have made to the definition to the actual database to keep it up to date.\n\nIf you have made a change to a model and need to generate a migration file:\n\n```./manage makemigrations```\n\nYou will then either need to restart your container so that these changes are applied:\n\n```docker compose -f local.yml down```\n\n```docker compose -f local.yml up -d```\n\nand these migrations are applied. Alternatively, to apply the latest migrations without restarting the container:\n\n```./manage migrate```\n\nSometimes migrations cannot be automatically generated, e.g. if two developers have both generated migration files and Django doesn't know which in which order they should be applied. If the two migrations are independent of one another (i.e. relate to different models) then Django can automatically merge these migration files for you by running:\n\n```./manage makemigrations --merge```\n\nand following the instructions.\n\nIf you have made changes to your models and have not generated a migration file then Django will warn you in the console output something like:\n\n```\n  Your models have changes that are not yet reflected in a migration, and so won't be applied.\n  Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.\n```\n\nNB In our case we would run the suggested `manage.py` commands via the Docker container in the way shown above, i.e.\n\n```./manage makemigrations```\n\nand\n\n```./manage migrate```\n\n\nIf your static files (css, js, fonts etc) have changed then on the production environments you will also need to refresh all of the static files in the deployed static folder.\n\n```docker compose -f production.yml run --rm django python manage.py collectstatic```\n\nAnswer 'yes' to the 'are you sure question'. It might say something like '0 files updated' but this message is notoriously misleading. Check to see whether the static files (js etc) being used are the ones you expect.\n\n### 8. Loading data fixtures\n\nTo take a snapshot of e.g. the production database and install it locally we do the following:\n\nGo to the production machine and run the following command:\n\n```sudo docker compose -f production.yml run --rm django python manage.py dumpdata --indent=4  --natural-foreign --natural-primary -a  \u003e dump.json```\n\nThis dumps all (-a) the data in the database into a json file that we can load locally. Check the end of the file to ensure there are no unexpected characters, particularly if you get an error similar to:\n```\njson.decoder.JSONDecodeError: Extra data: line 1722506 column 1 (char 53971086)\n```\n\nNow scp the json file to your local machine and run the following commands:\n\n\nFirst, remove existing database:\n\n```docker compose -f local.yml down -v```\n\nRebuild database:\n\n```docker compose -f local.yml up -d --build```\n\nRun the `src/loaddata.sh` script to load this:\n\n```sh\n./loaddata.sh dump.json\n```\n\n### 9. Requirements\n\nTo get a virtual environment outside of your docker environment (for example, to make your editor's language server work correctly), use `uv` (from the base directory):\n\n```bash\nuv venv --python 3.12\nuv pip install --requirements src/requirements/local.txt\n```\n\n### 10. Pre-commit\n\nThe requirements file for local development includes pre-commit. To set this up on your machine, make sure you're in the frrant directory and run:\n\n```pre-commit install```\n\nThis will ensure the hooks specified in `.pre-commit-config.yaml` are run prior to every commit. Black should automatically correct most formatting errors, so you can just try the commit again in most cases.\n\nYou can turn pre-commit off any time with `pre-commit uninstall` if you need to.\n\nIf pre-commit is not working, such as causing version problems with black, you can bring black, isort, etc. up to date with\n\n```pre-commit autoupdate```\n\n# Continuous Integration\nGitHub Actions are currently setup to run linter and pytest jobs on pull-requests and pushes to the development branch. For the linter tests we run the pre-commit hooks, and for pytest we build the docker stack and run the full set of pytest tests.\n\n# Deployment\n\nTo deploy we need to set some variables.\n\n(example shown for development, replace with production folder on production)\n\nUnder the folder `.envs` in the project folder (`ls -la` shows folders starting with `.`)\n\n`mkdir .development`\n\n`cd .development`\n\n`sudo vi .django`\n\nAnd enter the following:\n\n```\nUSE_DOCKER=yes\nIPYTHONDIR=/app/.ipython\nDJANGO_SETTINGS_MODULE=config.settings.development\nDJANGO_SECRET_KEY=\u003csecret key\u003e\nDJANGO_ADMIN_URL=admin/\nDJANGO_ALLOWED_HOSTS=\u003cdomain name\u003e\nURL_PREFIX=history/frrant-preprod/\n```\n\nIn the above, the domain name will be e.g. `frrd-dev.addev.ucl.ac.uk` for development. If more than one are required then they can be comma-separated (NB do not put inside braces `[]`)\n\nNext\n\n`sudo vi .pgadmin`\n\nenter the following:\n\n```\nPGADMIN_DEFAULT_EMAIL=\u003cusername\u003e\nPGADMIN_DEFAULT_PASSWORD=\u003cpassword\u003e\n```\n\nfor the username/password combo to use for pgadmin. This admin interface allows you to manage backups etc.\n\nFinally\n\n`sudo vi .postgres`\n\nand enter the following\n\n```\nPOSTGRES_HOST=postgres\nPOSTGRES_PORT=5432\nPOSTGRES_DB=frrant\nPOSTGRES_USER=devuser\nPOSTGRES_PASSWORD=\u003csecret password\u003e\n```\n\nfor the username/password to use for postgres database.\n\n\nIf your static files have changed in a deployment (css, js, fonts etc) then you need to run the 'collectstatic' command described earlier.\n\nThis development version will appear at the path\n`/history/frrant-preprod`. You can deploy it on a\ndevelopment machine as well, and it will appear\nat the path `https://localhost/history/frrant-preprod/`\n\n### SSL Certificates\n\nBefore building the nginx container we need to do the following for development (and production)\n\n`cd compose/development/nginx/certs`\n\n`sudo openssl req -x509 -nodes -days 365 -config rardselfsigned.cnf -newkey rsa:2048 -keyout rardselfsigned.key -out rardselfsigned.crt`\n\nThis will generated a certificate and corresponding key file.\n\n# Troubleshooting\n\nIf your deployment machine is light on space on `/var` then it is possible to request that Docker builds containers elsewhere by modifying the following file:\n\nThe file in question is:\n\n```sudo vi /etc/docker/daemon.json```\n\nSet its content to\n\n```\n{\n   \"graph\": \"/data/docker\"\n}\n```\n\nThen run:\n\n\n`sudo systemctl daemon-reload`\n`sudo systemctl restart docker`\n\n\nThen restart your container. This example will build containers on the `/data` directory instead of `/var`\n\n\nTo view running containers as a list:\n\n`sudo docker ps`\n\nto view logs for a particular container in the above list\n\n`sudo docker logs \u003ccontainerid\u003e -f`\n\nthe `-f` prints new lines as they are written. The `\u003ccontainerid\u003e` is the same shown in the output of `docker ps`\n\n\n## To clean up space on /var\n\nRemove yum caches\n\n`sudo yum clean all`\n\nIf your containers are built to `/var` this will clean those up\n\n`sudo docker system prune`\n\n\n## If your server becomes unreachable 30 minutes after restarting Docker\n\nYou need to ensure IP forwarding is enabled:\n\nEdit or create the file `/etc/sysctl.conf`\n\nadd or change the following line:\n\n`net.ipv4.ip_forward = 1`\n\nThen apply the settings with e.g.\n\n`service network restart`\n\n\nIf the Javascript and css is not looking how you expect after production, ensure you have run 'collectstatic' on the target machine(s). See the description given earlier.\n\n# Project management\nDuring the software development stage, we work in sprint cycles that go from 2 to 4 weeks, depending on workload and availability. These have a planning meeting at the beginning, a meeting with the research team to demo all new changes, and a deployment to production if all changes have been approved by the research team during the meeting. We are currently using [this Zenhub workspace](https://app.zenhub.com/workspaces/frrant-public-612e33d9c2bb690015527ab6/board?repos=312338365) to plan tasks in each sprint, and we share a [GitHub priority board](https://github.com/UCL/frrant/projects/7) with the research team to better understand what tasks are essential for them, and which can wait.\n\nPlans for next steps include running retrospectives in each internal sprint cycle, as well as making the pre-production/development server ready for the researchers so they can test and approve changes as we make them instead of waiting until the next meeting when we'll demo them live.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Ffrrant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucl%2Ffrrant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Ffrrant/lists"}