{"id":39257223,"url":"https://github.com/ccdc-opensource/on-site-webcsd","last_synced_at":"2026-01-18T00:18:28.167Z","repository":{"id":52307011,"uuid":"520409675","full_name":"ccdc-opensource/on-site-webcsd","owner":"ccdc-opensource","description":"On-Site WebCSD Installer","archived":false,"fork":false,"pushed_at":"2025-12-16T22:51:04.000Z","size":4895,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T13:19:36.911Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.ccdc.cam.ac.uk/solutions/software/on-site-webcsd","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccdc-opensource.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2022-08-02T08:13:21.000Z","updated_at":"2025-12-16T22:50:30.000Z","dependencies_parsed_at":"2023-02-18T21:10:15.169Z","dependency_job_id":"e86dd760-c656-4cef-9965-3fe4ee316b98","html_url":"https://github.com/ccdc-opensource/on-site-webcsd","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/ccdc-opensource/on-site-webcsd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccdc-opensource%2Fon-site-webcsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccdc-opensource%2Fon-site-webcsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccdc-opensource%2Fon-site-webcsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccdc-opensource%2Fon-site-webcsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccdc-opensource","download_url":"https://codeload.github.com/ccdc-opensource/on-site-webcsd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccdc-opensource%2Fon-site-webcsd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28523631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T23:53:28.710Z","status":"ssl_error","status_checked_at":"2026-01-17T23:52:20.131Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-01-18T00:18:25.684Z","updated_at":"2026-01-18T00:18:28.151Z","avatar_url":"https://github.com/ccdc-opensource.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# On-Site Lattice and WebCSD\n\n## Introduction\n\nOn-Site Lattice and WebCSD is currently only available to CCDC industrial customers and other invited groups.\n\nThis readme contains information required for installation and updates of On-Site Lattice and WebCSD.\n\nTerms and conditions can be found in the `license.md` file.\n\nAdditional information including user configuration and troubleshooting can be found in the wiki at \u003chttps://github.com/ccdc-opensource/on-site-webcsd/wiki\u003e.\n\n## Prerequisites and Setup\n\n### System Requirements\n\nFor version 4.0 onwards, a postgres server is required for CSD and Identity databases.\nThis will typically be installed on a separate machine from the one hosting the WebCSD\nDocker containers.\n\nRecommended requirements for postgres server without Macromolecule Hub (PDB protein data):\n\n- Postgres version 14 or newer\n- 100GB free hd space\n\nRecommended requirements for postgres server including Macromolecule Hub:\n\n- Postgres version 14 or newer\n- 200GB free hd space\n\nRecommended requirements for Docker server hosting On-Site Lattice and WebCSD containers:\n\n- 30GB free hd space, 16GB RAM, 8 core CPU.\n\nOn-Site Lattice and WebCSD should work with any Linux OS that meets the requirements to run Docker, but official support is provided by CCDC on the following platforms.\nNote that these match the 2024.2 Desktop release.\n\n- RedHat Enterprise Linux 8 and 9\n- Rocky Linux 8 and 9\n- Ubuntu LTS 22 and 24\n\n### Authentication\n\n- A valid CCDC activation key will be required to use the software.\n- Access to the CCDC docker container registry will require a username and password, to get them please contact CCDC Support.\n- The postgres CSD database will be provided via a download link. To obtain this, please contact CCDC Support\n  and specify whether you want the database with or without Macromolecule Hub.\n\n### Docker Installation\n\nA standard [Docker Server](https://docs.docker.com/engine/install/#server) and [Docker Compose](https://docs.docker.com/compose/install/) installation is required for installation of WebCSD.\nWe recommend installing the latest version of Docker from these links.\nWebCSD will run on [Docker Desktop](https://docs.docker.com/engine/install/#desktop), however this is not recommended and may [require a license](https://www.docker.com/legal/docker-subscription-service-agreement/).\n\nCHECK: Test your Docker installation as described at the above links. Also verify that you can log into the CCDC\ncontainer registry.\n\n```sh\ndocker login -u \u003cuser\u003e -p \u003cpassword\u003e ccdcrepository.azurecr.io\n\n# or to be prompted for the password\ndocker login -u \u003cuser\u003e --password-stdin ccdcrepository.azurecr.io\n```\n\n### PostgreSQL Server Installation\n\nOnce you have downloaded the postgres CSD database, please follow the instructions at\n[Setting Up Your PostgreSQL Server](https://github.com/ccdc-opensource/on-site-webcsd/wiki/Setting-up-your-PostgreSQL-server) to restore\nthe database into your environment.\n\nCHECK: Can you connect to the database from Docker containers? These commands should run without errors.\n\n```sh\n# Pull postgres image\ndocker pull postgres:14.13 \n# Run container\ndocker run --name debug-postgres -e POSTGRES_PASSWORD=passwordhere -d postgres:14.13 \n# Shell into container\ndocker exec -it debug-postgres sh \n# Attempt to establish a connection to the database server\npsql -h database.server.name -p 5432 -U postgres -d csd-database\n```\n\n## Basic Configuration And Installation\n\n### SSL Configuration\n\nConnecting to your WebCSD server via https is now required.\nTo configure this you will need an SSL certificate and private key.\nAsk your local IT staff to set these up for you.\n\nPlease follow the instructions at [Configuring SSL](https://github.com/ccdc-opensource/on-site-webcsd/wiki/Configuring-SSL).\nIf the WebCSD server is run without configuring SSL a built-in self-signed certificate will be used.\nThis is not recommended as it is insecure.\n\n### WebCSD Basic Installation\n\nPlease download and unpack the latest version from the release tab \u003chttps://github.com/ccdc-opensource/on-site-webcsd/releases\u003e.\n\nAfter unpacking the release source code onto the server on which the software will be installed you will need to go into the on-site-webcsd directory and copy the environment file `sample.env` to `.env`.\nThen open the `.env` file and populate with suitable values.\n\n```console\ncd on-site-webcsd\ncp sample.env .env\n```\n\nYou will need to update the `.env` file with your licence key, your database server details and\nthe URL you will use for your WebCSD server.\nHere is an example of the `.env` file with comments removed:\n\n```console\nCCDC_LICENSING_CONFIGURATION=la-code;123456-123456-123456-123456-123456-123456;\nDB_CONNECTIONSTRING=Server=database-server;Port=5432;User Id=postgres;Password=passwordhere\nPUBLIC_URI=https://csd-software.local\nPLATFORM_PORT=443\nCSD_DATABASE=csd-database\nIDENTITY_DATABASE=csd-identity\n```\n\nWhere stated, some of these variables will be provided by CCDC; all other variables are for the user to generate and set.\nOnce the variables file has been populated, login to the CCDC container registry and bring up the stack:\n\n```console\ndocker login -u \u003cuser\u003e -p \u003cpassword\u003e ccdcrepository.azurecr.io\n\n# or to be prompted for the password\ndocker login -u \u003cuser\u003e --password-stdin ccdcrepository.azurecr.io\n\n# As of v2.0.0, containers run as non root users.\n# Because of this you will need to create the CCDC user if it does not already exist.\nsudo adduser ccdc --uid=1397\n\n# If you are upgrading from an older version to v4.0.0, ensure the user id is set to 1397\nsudo usermod -u 1397 ccdc\n\n# You will also need to ensure the user \"ccdc\" has read access to any in-house or CSP databases.\n# E.g. if these are in the csd-data directory:\nsudo chown -R ccdc:ccdc csd-data/ \n\n# For testing use one of the following commands.\n# These do not load in-house databases and the user access control is disabled.\n# These features will be configured later.\n\n# If you are not using Macromolecule Hub\ndocker compose -f docker-compose.yml -f docker-compose.ssl.yml -f docker-compose.disable-user-access.yml up -d\n\n# If you are using Macromolecule Hub\ndocker compose -f docker-compose.yml -f docker-compose.ssl.yml -f docker-compose.disable-user-access.yml -f docker-compose.macromolecule-hub.yml up -d\n```\n\nCHECK: To check that the install has completed and that all the services are running, run:\n\n```sh\ndocker compose ps\n```\n\nwhich should show the state of the services to all be `Up`. If any services have the state `Up (unhealthy)` or `Exit` then restart the stack.\n\n```sh\n# Include all config files from the \"docker compose ... up -d\" run earlier\ndocker compose -f docker-compose.yml -f ... down\n# Same command to bring up the stack as before\ndocker compose -f docker-compose.yml -f ... up -d\n```\n\nIf the issues persist then please contact CCDC Support.\n\nFor more information see the [Docker volumes documentation](https://docs.docker.com/compose/compose-file/#volumes).\n\nTo access the On-Site Lattice and WebCSD service locally go to \u003chttps://full.server.hostname\u003e in a browser,\nreplacing `full.server.hostname` by the full hostname of your Docker host. Check that you can search the CSD.\nIf you have problems check that `PUBLIC_URI` has been set to \u003chttps://full.server.hostname\u003e in `.env`.\n\n## Further Configuration\n\nYour On-Site WebCSD server is now up and running but you will probably need to configure user access control\nand in-house databases. This is done via docker compose files\n(see [WebCSD Configuration Files](https://github.com/ccdc-opensource/on-site-webcsd/wiki/WebCSD-configuration-files) in the wiki).\nAfter making any changes to these files, restart the stack as described above, adding any docker compose files\nwhich you have customised into the `docker compose ... up -d` command.\n\n### User Access Control\n\nUser access control can be managed via local accounts or Single Sign-On (SSO).\nUnless it is explicitly disabled via `docker-compose.disable-user-access.yml`, you must configure roles to allow\naccess to in-house databases.\n\nFor details please see [Access Control To In-House Databases](https://github.com/ccdc-opensource/on-site-webcsd/wiki/Access-control-to-in-house-databases).\n\n### In-house Database Configuration\n\n:warning: **OnSite WebCSD assumes structure identifiers are unique across all registered in-house databases.\nYou will likely encounter unexpected behaviour if this is not the case.**\n\nOn-Site Lattice and WebCSD can be configured to read from in-house databases.\n\nProvided within the installation is a sample database `teaching-subset.csdsql` which can be found in the `sample-data` folder in the root of the installation.\n\nTo enable in-house databases:\n\n1. Copy and rename the file `docker-compose.sample-On-Site-only-db-config.yml` to `docker-compose.db-config.yml`\n2. Edit the `volumes` section of that file to point to any in-house databases and edit the `environment` section to configure the application to recognise these databases.\nEnsure that all instances of 'database-1' or 'database-2' are replaced with the actual database name.\n\nFor example, to use the 'teaching_subset.csdsql' database and have it appear as a database named 'Example', your docker-compose.db-config.yml should look like:\n\n```yml\nvolumes:\n    - /path/to/webcsd/sample-data/teaching_subset.csdsql:/csd-data/teaching_subset.csdsql\nenvironment:\n    - ServiceSettings__Databases__2__Name=Example\n    - ServiceSettings__Databases__2__ConnectionString=/csd-data/teaching_subset.csdsql\n```\n\nMore information is given in the notes \u0026 example sections of the sample file. This acts as an [override file](https://docs.docker.com/compose/extends/) which you will have to include in the startup command.\n\n### In-house Protein Database Creation and Configuration\n\nIf you have a Macromolecule Hub licence, you can also create and register in-house protein databases for use within OnSite WebCSD.\n\nTo create an In-house Protein Database, you will need the Python Utilities. These can be downloaded from the [CCDC Downloads page](https://www.ccdc.cam.ac.uk/support-and-resources/csdsdownloads/)\nunder `CSD Python API \u003e Python CSD Python API Utilities`. If you do not see the CSD Python API listed in the available downloads, you may need to sign in.\nThe relevant script can be found under `ccdc \u003e utitities \u003e create_protein_database`.\nYou can run the script using the CSD Python API version 3.3.0 or later.\n\nOnce you have created your protein database, you can register it by adding to your `docker-compose.db-config.yml` file following the instructions above.\nYou must then mark the database as a protein database. Your database config should look something like this:\n\n```yml\nvolumes:\n    - /path/to/ExampleProteinDb.csdsqlx:/csd-data/ExampleProteinDb.csdsqlx\nenvironment:\n    - ServiceSettings__Databases__2__Name=Example Protein DB\n    - ServiceSettings__Databases__2__ConnectionString=/csd-data/ExampleProteinDb.csdsqlx\n    - ServiceSettings__Databases__2__Speciality__0=Protein\n```\n\n### CSD-Theory Web Database Configuration\n\nInstructions on setting up CSD-Theory Web can be found in the [wiki](https://github.com/ccdc-opensource/on-site-webcsd/wiki/Setting-up-CSD%E2%80%90Theory-Web).\n\nProvided within the installation is a sample CSD-Theory landscape database `CSPLandscape.csdsqlx` which can be found in the `sample-data` folder in the root of the installation,\nalong with a blank `CSPDatabase.db` CSD-Theory metadata database.\n\n### Other customisations\n\nFor other optional customisations to your WebCSD server please see [WebCSD Configuration and Customisation](https://github.com/ccdc-opensource/on-site-webcsd/wiki/WebCSD-Configuration-\u0026-Customisation).\n\n## Updates\n\nWhen you have been notified that there is an update available you can [download the newest release](https://github.com/ccdc-opensource/on-site-webcsd/releases) from the github repository.\nOnce you have downloaded the new release, ensure any customisations have been copied to the new release directory.\nYou may need to customise the new versions of the config files (particularly `.env`) rather than copying the old versions - check the website above for breaking changes.\n\nOnce the latest installation files have been obtained, to update the software, pull the latest images, and restart the stack.\nThe latest images can be pulled whilst the stack is running and changes will only come into effect upon restarting the stack.\n\n```sh\ndocker compose pull\n\n#Include all files you included when bringing up the stack\ndocker compose -f docker-compose.yml -f ... down\n#Use one of the following commands: \n\n#Use this command if you have no in-house databases and don't want to use macromolecule hub\ndocker compose -f docker-compose.yml -f docker-compose.ssl.yml up -d\n\n#Use this command if you have in-house databases and don't want to use macromolecule hub \ndocker compose -f docker-compose.yml -f docker-compose.db-config.yml -f docker-compose.ssl.yml up -d\n\n#Use this command if you have in-house databases and want macromolecule hub \ndocker compose -f docker-compose.yml -f docker-compose.macromolecule-hub.yml -f docker-compose.db-config.yml -f docker-compose.ssl.yml up -d\n\n#Use this command if you have no in-house databases and want macromolecule hub\ndocker compose -f docker-compose.yml -f docker-compose.macromolecule-hub.yml -f docker-compose.ssl.yml up -d\n```\n\n## Contacting support\n\nIf you experience any difficulties with installing or using On-Site Lattice and WebCSD, please contact our support team at \u003csupport@ccdc.cam.ac.uk\u003e who will be happy to assist you.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccdc-opensource%2Fon-site-webcsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccdc-opensource%2Fon-site-webcsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccdc-opensource%2Fon-site-webcsd/lists"}