{"id":25895435,"url":"https://github.com/diamondlightsource/synchweb","last_synced_at":"2026-03-17T11:01:06.358Z","repository":{"id":28385171,"uuid":"31899330","full_name":"DiamondLightSource/SynchWeb","owner":"DiamondLightSource","description":"ISPyB web application","archived":false,"fork":false,"pushed_at":"2026-03-16T14:43:56.000Z","size":24635,"stargazers_count":19,"open_issues_count":19,"forks_count":30,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-03-16T23:51:42.636Z","etag":null,"topics":["experiment","ispyb","javascript","metadata","php","synchrotron","xray-crystallography","xray-scattering-experiments"],"latest_commit_sha":null,"homepage":"http://diamondlightsource.github.io/SynchWeb/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DiamondLightSource.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":"2015-03-09T13:20:54.000Z","updated_at":"2026-03-02T13:19:38.000Z","dependencies_parsed_at":"2023-10-04T15:42:53.502Z","dependency_job_id":"87799769-f732-4a52-9cd6-d19915b3fa56","html_url":"https://github.com/DiamondLightSource/SynchWeb","commit_stats":null,"previous_names":[],"tags_count":106,"template":false,"template_full_name":null,"purl":"pkg:github/DiamondLightSource/SynchWeb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiamondLightSource%2FSynchWeb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiamondLightSource%2FSynchWeb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiamondLightSource%2FSynchWeb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiamondLightSource%2FSynchWeb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DiamondLightSource","download_url":"https://codeload.github.com/DiamondLightSource/SynchWeb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiamondLightSource%2FSynchWeb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30622417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T08:10:05.930Z","status":"ssl_error","status_checked_at":"2026-03-17T08:10:04.972Z","response_time":56,"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":["experiment","ispyb","javascript","metadata","php","synchrotron","xray-crystallography","xray-scattering-experiments"],"created_at":"2025-03-02T22:31:21.602Z","updated_at":"2026-03-17T11:01:06.281Z","avatar_url":"https://github.com/DiamondLightSource.png","language":"JavaScript","readme":"# SynchWeb\nSynchWeb is an ISPyB web application which consists of a PHP REST API and a Backbone/Marionette javascript client.\nThe client includes some newer components written in Vue.js\n\nRead More: https://diamondlightsource.github.io/SynchWeb/\n\n## Installation\nRunning SynchWeb requires setting up a Linux, Apache, MariaDB and PHP (LAMP) software stack. If running in production you should configure your Apache and PHP to serve secure pages only. The steps below describe how to build the software so it is ready to deploy onto your target server. \nThe [podman](./podman) folder provides support for creating a containerised \nproduction deployment. Full instructions [here](./podman/README.md).\n\nFor development (not production use), a simple environment can be setup by using scripts provided \n[here](https://github.com/DiamondLightSource/synchweb-devel-env). Support is provided for both \ncontainerisation and the use of VMs. VS Code provides a good development environment for working\nwith the SynchWeb codebase.  PHP Tools extension provides intellisense, debugging, formatting, \nlinting and support for unit tests. Vetur and Volar extensions provide support for working with \nthe Vue.js code. They are not intended for production use but include scripts to automatically\n build and deploy the software on a local VM or in a Podman container.\n\n### Requirements\nIf not using the Podman containter, to build SynchWeb on a machine you will need the following on the build machine:\n\n- [npm](https://docs.npmjs.com/) \n- [composer](https://getcomposer.org/)\n- appropriate version of PHP on the build machine\n\nIf not using the development VMs you will also need an instance of the\nISPyB database - available\n[here](https://github.com/DiamondLightSource/ispyb-database).\n\nIf not already installed, you must install the following packages:\n\n```\nphp php-mysqlnd php-mbstring php-xml php-gd php-fpm php-cli php-xdebug\n```\n\n### Check out the code\n```sh\n$ git clone https://github.com/DiamondLightSource/SynchWeb\n```\n\n### Customise front end - config.json\nAn example configuration is provided in `client/src/js/config_sample.json`\nThis file should be copied to create a `client/src/js/config.json` file and edited to customise the application for your site.\n\n| Parameter | Description |\n| ------ | ------ |\n| apiurl | Base API root path of back end services e.g. /api |\n| appurl | Base API root path of client app, normally not required \"\"|\n| production | deprecated with webpack build |\n| build | git hash of current build, used if dynamic reload of pages required post deployment|\n| pucks | Array that lists default number of puck positions in sample changers for beamlines |\n| gsMajorAxisOrientation | Determines whether the major grid scan axis determines the orientation of the view |\n| maintenance_message | Can be used so app serves static page under maintenance periods |\n| maintenance | Flag to indicate if client is in maintenance mode|\n| ga_ident | Google Analytics id|\n| site_name | Site Name to display in footer |\n| site_link | URL to site home page |\n| data_catalogue | Object that includes name and url property for a link to a data catalogue - displayed on the landing page |\n\nSite Image can be customised via the tailwind.config.js header-site-logo and footer-site-logo values.\n\n### Build front end\nSee package.json for the full list of commands that can be run.\n\n```sh\n$ cd SynchWeb/client\n$ npm install\n$ npm run build\n```\n\n### Customise back end - config.php\nAn example configuration is provided in `api/config_sample.php`.  This should be copied to\n`api/config.php` and updated to include appropriate configuration details.\n\nMain items to change include:\n- database connection parameters (user, password, host, port)\n- authentication type (cas, ldap, dummy/no authentication)\n\n### Build backend\n```sh\n$ cd SynchWeb/api\n$ composer install\n```\n\nNote, the front and backend are built automatically in the Podman deployment.\n\n### Run backend tests\nTests are available for the PHP code under `api/tests`.  To run these, go to the `api` directory and use:\n\n```sh\n$ cd SynchWeb/api\n$ ./vendor/bin/phpunit --verbose -c tests/phpunit.xml\n```\nNote, a single test can be run by specifying that instead of the `tests` directory.  Tests\nwill also produce a coverage report - this can be disabled by specifying `--no-coverage` when\nrunning the tests.\n\n### Debugging back end tests\nIt is possible to debug the php tests.  Install xdebug and using an IDE such as VS Code.  You\ncan then start the debugger in the IDE and put break points in the code.  Running the tests\n(from the command line or within VS Code) will trigger the debugger and execution will be\nhalted on break points or specified error types.\n\n### Run front end tests for Vue.js\nTesting on the front end is restricted to the newer Vue.js code as it is \nanticipated that the older code will eventually be migrated to this form.\nTo run these tests, \n\n```sh\n$ cd SynchWeb/client\n$ npm run test\n```\n\n## Developing the client application\nIt is possible to run the client code on a local machine and connect to an existing SynchWeb installation on a server.\nThe steps required are to build the front end code and then run a webpack dev server to host the client code.  Note, this is possible for both the\nPodman and VM approach detailed [here](https://github.com/DiamondLightSource/synchweb-devel-env).\n```sh\n$ cd SynchWeb/client\n$ npm run build:dev\n$ npm run serve -- --env port=8080 --env.proxy.target=http://localhost:8082\n```\nIn this example a browser pointed at localhost:9000 will connect to a SynchWeb back end on localhost:8082. Don't ignore the middle '--' otherwise the dev server will not receive the arguments!\n\nThe command line options available are described in this table. These override the defaults set in webpack.config.js.\n\n| Parameter | Description |\n| ------ | ------ |\n| env.port | Webpack dev server port |\n| env.proxy.target | Full address of the SynchWeb PHP backend server (can include port if required) |\n| env.proxy.secure | Flag to set if connecting to an https address for the SynchWeb backend.  Setting to `false` can also help with self-signed SSL certs (which may be insecure so should not be used in production). |\n\n## Continuous Integration\nBasic CI is included via the GitHub workflows functionality, defined by\n`.github/workflows/ci.yml`.  Currently this will run whenever a branch change or\npull request is pushed to `master`, `pre-release` or `release`.  The workflow will run two parallel jobs:\n\n* Checkout the SynchWeb code - for the PHP build\n  1. Install the correct version of PHP\n  1. Validate the `composer.json` file\n  1. Set up a cache for the composer dependencies\n  1. Install the required composer dependencies\n  1. Run the PHP unit tests - using PHPUnit\n  1. Run linting against the PHP code, using PSalm\n* Checkout the SynchWeb code - for the JavaScript build\n  1. Install npm dependencies (using `ci` mode)\n  1. Build the JavaScript bundle\n  1. Run Vue unit tests\n  1. Run basic JavaScript linting\n  1. Run Vue linting\n\nNote, currently the workflows will not fail if linting errors or warnings are \nencountered - this is to enable an initial period of tidying to be enacted.  Once \nthe code is in a suitable state, the rules should be tightened to prevent changes \nthat introduce new issues.\n\n## Work in Progress\nThe codebase is currently subject to some degree of refactoring.  The front end is being gradually \nmigrated away from its Backbone/Marionette origins to use Vue.js instead.  Additionally, the\nPHP back end is being updated to have a more structured form - breaking down the Page monolith \nclasses into a more layered architecture - with data layer services under the `Model` folder, and\ncontroller/service classes under the `Controllers` folder.  The intention here is to isolate data\naccess code in a separate layer to allow a more formal API to be identified and to decouple the code\nto simplify testing and maintenance.  The `Controllers` code currently combines what could be \nfurther split into separate controller and service classes if this was deemed worthwhile (e.g. to \nfacilitate code reuse).  Dependency injection is being introduced (see `index.php`) using the Slim\nframework.  This could potentially be simplified if common conventions are introduced (e.g. similar \nto those used in `Dispatch.php` for setting up the original routes).  Once more formal APIs are \nidentified, it may make sense to introduce proper interfaces to codify these.  Swagger-like tools \ncan then be used to improve documentation and testing of exposed web APIs.\n\n### Acknowledgements\n----------------\nIf you make use of code from this repository, please reference:\nFisher et al., J. Appl. Cryst. (2015). 48, 927-932, doi:10.1107/S1600576715004847\nhttps://journals.iucr.org/j/issues/2015/03/00/fs5101/index.html\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiamondlightsource%2Fsynchweb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiamondlightsource%2Fsynchweb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiamondlightsource%2Fsynchweb/lists"}