{"id":20915978,"url":"https://github.com/indico/mereswine","last_synced_at":"2025-10-17T05:15:02.520Z","repository":{"id":45124005,"uuid":"20717174","full_name":"indico/mereswine","owner":"indico","description":"Aggregate community-submitted data about running instances of your software project","archived":false,"fork":false,"pushed_at":"2022-01-06T22:24:11.000Z","size":787,"stargazers_count":3,"open_issues_count":10,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-10T02:14:07.333Z","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":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indico.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-11T07:58:26.000Z","updated_at":"2022-09-14T11:48:06.000Z","dependencies_parsed_at":"2022-09-16T13:22:10.475Z","dependency_job_id":null,"html_url":"https://github.com/indico/mereswine","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indico%2Fmereswine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indico%2Fmereswine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indico%2Fmereswine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indico%2Fmereswine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indico","download_url":"https://codeload.github.com/indico/mereswine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225206885,"owners_count":17438200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-11-18T16:19:13.134Z","updated_at":"2025-10-17T05:14:57.488Z","avatar_url":"https://github.com/indico.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mereswine\n\n![Mereswine logo](https://raw.githubusercontent.com/indico/mereswine/master/mereswine/static/logo.png)\n\nWith the Mereswine package you'll be able to easily track and manage the various instances of your application, as well as analizing interesting statistical information.\n\n## Installation (production)\n\nFirst of all, we recommend that you install Mereswine in a virtual environment:\n\n```sh\n$ virtualenv .venv\n$ source .venv/bin/activate\n```\n\n### From PyPI\n\nThis is the easiest way to install Mereswine:\n\n```sh\n$ pip install mereswine\n```\n\n## Installation from Git\n\nIf instead you want/need to install a development version of the package, head to your code directory and clone this\nrepository:\n\n```sh\n$ git clone https://github.com/indico/mereswine.git\n$ cd mereswine\n```\n\nThen, making sure you are still in your virtual environment, install it with Pip:\n\n```sh\n$ pip install .\n```\n\nIf you are instead doing development on Mereswine, you can link your current repo to your `site-packages`:\n\n```sh\n$ pip install -e .\n```\n\n## Configuration\n\nAfter you installed the package, you should create your own config file\n\n```sh\n$ cp mereswine/mereswine.cfg.example /somewhere/safe/mereswine.cfg\n```\n\nand personalize it. Keep in mind that `mereswine.cfg` is executed as Python code and thus needs to be valid Python.\n\nYou will then have to define an environment variable:\n\n```sh\n$ export MERESWINE_CONFIG=/path/to/mereswine.cfg\n```\n\n## Running development server\n\nYou can easily run a Mereswine development server:\n\n```sh\n$ mereswine run\n```\n\nThere is also a `mereswine.wsgi` file included in the distribution, which can be used by WSGI containers.\n\n### Secret key\n\nThe first thing to do is to fill the `SECRET_KEY` field.\n\nJust add whichever key you prefer or insert a random alphanumeric string.\n\n### Timezone and time format\n\nThe fields `BABEL_DEFAULT_TIMEZONE` and `BABEL_DEFAULT_LOCALE` determine, respectively, in which timezone the times will be shown and in which format.\n\nThe default values are `UTC` for the timezone and `en_GB` (i.e. English format) for the time format.\n\n### Application name\n\nTo personalize your Mereswine application you should change the field `APP_NAME` to your application name.\n\n### Crawling endpoints\n\nTo allow Mereswine to crawl additional information from the servers running your application, you should specify all the necessary endpoints in the `CRAWLING_ENDPOINTS` field.\n\nThis field is going to be a Python list where each element is a Python dictionary containing an `url` and (optionally) a `headers` dictionary. Each endpoint url will be appended to the server base url at the moment of sending the http request to crawl the information.\n\n### Crawled fields\n\nAll the configurations relative to the crawled fields are managed through the `CRAWLED_FIELDS_SETTINGS` field, which is going to be a dictionary of dictionaries.\n\nEach field must have a key name equals to the corresponding crawled field name. Any mismatching field will be ignored.\n\nIn case you want to ignore some of the fields that the crawling endpoints offer, it is possible to set the fields to `None` and your Mereswine application will not show them in the interface.\n\nFor each field, the following parameters can be specified:\n\n- **label:** a string that specifies how the field name will be rendered across Mereswine. The default value is the field name with spaces instead of underscores and with the first word starting with a capital letter;\n- **chart:** a boolean value that indicates whether to include or not that field amongst the statistics. Default: `False`;\n- **chart_type:** if `chart` is set to `True` it specifies with which kind of chart the field statistics will be displayed. Accepted values are: `'bar'`, for a barchart, `'line'`, for a linechart, and `'pie'`, for a piechart. Default: `'bar'`;\n- **aggregation:** if the field cannot be directly shown (for example it's a list or a dictionary) you have to define an aggregation function to aggregate the values inside the field and use the aggregated value instead. At the moment, only numeric values are supported and the accepted aggregation functions are: `None`, when no aggregation is necessary, `'sum'`, to aggregate by sum, `'avg'`, to aggregate by average, and `'min'` and `'max'` to show the lowest and the highest value, respectively. Default: `None`;\n- **chart_aggregation:** similar to `aggregation`, it specifies an aggregation function that will be used in the statistics chart, if `chart` is set to `True`. Accepted values are: `'count'`, to show the number of instances per each category, `'sum'`, `'avg'`, `'min'` and `'max'`. Default: `'count'`;\n- **chart_aggregate_by:** a string that specifies by which (other) field the current field should be aggregated in the statistics chart. It can be any of the other crawled fields or `'country'`. Be wary that if `chart_aggregation` is set to `'count'` this field will be ignored. Default: `'country'`.\n\n### Celery periodic task\n\nTo specify the time interval between each periodic crawl, you should modify the `CELERYBEAT_SCHEDULE` field.\n\n### Authentication\n\nMereswine uses [Flask-Multipass](https://flask-multipass.readthedocs.io) to provide different authentication systems.\nKeep in mind that Flask-Multipass should be configured in `mereswine.cfg` as mentioned in its documentation and as can\nbe seen in the example settings file. In addition you should specify in `USER_WHITELIST` the identifiers the users\nhave in the authentication systems being used so that they can access Mereswine, thus preventing that every user\nregistered in these systems can access Mereswine unrestrictedly.\n\n## API implementation\n\nTo allow your application, and therefore each instance running it, to communicate with Mereswine you have to use the three APIs available:\n\n- **Create instance:** this API is used to create a new instance record in the Mereswine DB.\n    - *Endpoint:* `/instance/`;\n    - *Request type:* `POST`;\n    - *Data:* the url of the instance server, the contact person name and e-mail address and the organization name;\n    - *Response:* the instance UUID.\n- **Update instance:** used to update the instance record in the Mereswine DB whenever some field is changed in the instance server. Also used when the Instance Tracking has to be be enabled/disabled for that instance.\n    - *Endpoint*: `/instance/\u003cuuid\u003e`;\n    - *Request type:* `PATCH`;\n    - *Data:* every combination of the following fields: server url, contact person name, contact e-mail address and enabled status (`True` or `False`);\n    - *Response:* a summary of the instance main information in json format.\n- **Get instance:** used to retrieve the main information of a certain instance.\n    - *Endpoint:* `/instance/uuid`;\n    - *Request type:* `GET`;\n    - *Data:* none;\n    - *Response:* a summary of the instance main information in json format (like for the update API).\n\n## Usage\n\nMereswine is basically composed by two main functionalities: instance details \u0026 management and statistics.\n\nFor others more advanced functionalities a python script has been written and included in the package.\n\n### Instance details \u0026 management\n\nMereswine allows you to view a comprehensive list of all the instances in the DB, with the possibility to filter them by a few criteria. Also in the server list you can sort the instances selected by one of the available fields (be it one of the main fields or one of the crawled fields) and you can choose to run at any moment the crawler to crawl all the instances.\n\nBy clicking on the detail button for a specific instance, you'll be able to explore it's main and crawled information and see a map with the approximated physical location of the server.\n\n### Statistics\n\nIn the statistics page you'll see the country distribution by default, i.e. the position on the map of the servers in the DB and the percentage of servers for each country.\n\nOn top of that, it will also be displayed all the additional charts you might have configured in the settings file.\n\n### Command line script\n\nFor more advanced operations you'll have to use the Mereswine CLI and the custom commands mereswine offers.\n\nTo use the script run\n\n```sh\nmereswine \u003carguments\u003e\n```\n\nThe available arguments and possibile operations are the following:\n\n- **run:** run a development web server;\n- **shell:** run a Python shell with access to the DB;\n- **db drop:** drops all the DB tables;\n- **db create:** creates the DB tables;\n- **db recreate:** drops all DB tables and creates new tables (same as *drop* and then *create*);\n- **crawl [uuid]:** crawl a specific instance (if *uuid* is passed) or all the active instances;\n- **celery:** invoke celery (e.g. to set up a worker)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findico%2Fmereswine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findico%2Fmereswine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findico%2Fmereswine/lists"}