{"id":40773082,"url":"https://github.com/performant-software/dm-2","last_synced_at":"2026-01-21T18:56:22.597Z","repository":{"id":37500446,"uuid":"127151469","full_name":"performant-software/dm-2","owner":"performant-software","description":"Digital Mappa (DM for short) is a freely available online environment for creating projects out of digital images and texts. ","archived":false,"fork":false,"pushed_at":"2024-10-29T21:13:39.000Z","size":2988,"stargazers_count":20,"open_issues_count":90,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-29T21:39:25.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.digitalmappa.org","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/performant-software.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-28T14:19:35.000Z","updated_at":"2024-10-14T21:20:19.000Z","dependencies_parsed_at":"2024-10-26T01:25:08.489Z","dependency_job_id":"08a30f89-ba7a-404b-aeb6-cad5c0398d49","html_url":"https://github.com/performant-software/dm-2","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/performant-software/dm-2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/performant-software%2Fdm-2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/performant-software%2Fdm-2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/performant-software%2Fdm-2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/performant-software%2Fdm-2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/performant-software","download_url":"https://codeload.github.com/performant-software/dm-2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/performant-software%2Fdm-2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28639900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T18:04:35.752Z","status":"ssl_error","status_checked_at":"2026-01-21T18:03:55.054Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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-21T18:56:20.905Z","updated_at":"2026-01-21T18:56:22.578Z","avatar_url":"https://github.com/performant-software.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Digital Mappa 3\n============================================\n\n[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)\n\nDigital Mappa 3 (DM3 for short) is a freely available online environment for creating projects out of digital images and texts. The premise of DM3 is simple and powerful: if you have a collection of digital images and/or texts, you should be able to produce an online resource that links together specific moments on these images and texts together, annotate these moments as much as you want, collaborate with others on this work, have the content you produce be searchable, and publish this work to others or the public as you wish. And you should be able to do this with little technical expertise.\n\nDM3 was developed under the direction of Martin Foys and his team at the University of Wisconsin-Madison and Dot Porter at the Schoenberg Institute for Manuscript Studies. Funding was provided through a grant from the National Endowment for the Humanities and through funding from UW Madison. Performant Software Solutions LLC (www.performantsoftware.com) performed the software development, with Andy Stuhl, Nick Laiacona, Derek Leadbetter, and Ben Silverman as primary contributors.\n\nDM3 design was inspired by the DM project (https://github.com/performant-software/DM) developed originally at Drew University by Martin Foys and others.\n\n- [Technical overview](#technical-overview)\n- [Heroku installation](#heroku-installation)\n  * [Create app](#create-app)\n  * [Provision resources](#provision-resources)\n  * [Configuration variables](#configuration-variables)\n  * [Set up database](#set-up-database)\n- [Local installation](#local-installation)\n  * [With Docker Compose](#with-docker-compose)\n    + [Development environment](#development-environment)\n    + [Production environment](#production-environment)\n  * [With Heroku local development environment](#with-heroku-local-development-environment)\n    + [Requirements](#requirements)\n    + [Setup](#setup)\n  * [Manually](#manually)\n- [Active Storage](#active-storage)\n- [Upgrade from 0.x](#upgrade-from-0x)\n\nTechnical overview\n---------------\n\nDM3 is a single page React application backed by a Ruby on Rails server running a Postgres database. It uses Active Storage for image uploads and ImageMagick for image processing. It is primarily built to use Amazon S3 for image storage. It has been developed within the Heroku (heroku.com) environment but has no Heroku specific dependencies. Issues are tracked and releases are issued on the [DM3 GitHub repo](https://github.com/performant-software/dm-2).\n\n\nHeroku installation\n-------------\n\n### Create app\n\nTo install DM3 on Heroku, use the \"Deploy to Heroku\" button above.\n\nYou may also create a new app and point it at this repository using the following command with the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli):\n\n```sh\nheroku create --stack heroku-24\n```\n\nYou will need to activate both the Ruby and Node.JS buildpacks. This can be done from the Heroku CLI:\n\n```sh\nheroku buildpacks:set heroku/ruby\nheroku buildpacks:add --index 1 heroku/nodejs\n```\n\n### Provision resources\n\nThis app requires at least 1x worker dyno and 1x web dyno.\n\nYou will also need to provision Heroku Postgres, and Heroku Redis using the Heroku Resources section.\n\nNext, you will need to provision an email provider. Heroku provides many options as add-ons, but you may also simply provision an external email service and fill in the appropriate config variables in the next step. For example, the official Digital Mappa instances use the external service Postmark.\n\nFinally, you will need to provision an Amazon S3 bucket to store the uploaded image files and configure access using Amazon IAM. Once a S3 bucket has been created you will need to set Cross-origin resource sharing (CORS) in the permissions tab of the S3 bucket. See https://aws.amazon.com/ for more information.\n\n### Configuration variables\n\nThe following config variables should be set for the application:\n\n```\nAWS_ACCESS_KEY_ID\nAWS_BUCKET\nAWS_REGION\nAWS_SECRET_ACCESS_KEY\nEMAIL_FROM\nEMAIL_PASSWORD\nEMAIL_PORT\nEMAIL_SERVER\nEMAIL_USERNAME\nHOSTNAME\nLANG\nMALLOC_ARENA_MAX\nPROTOCOL\nRACK_ENV\nRAILS_LOG_TO_STDOUT\nRAILS_SERVE_STATIC_FILES\nREDIS_PROVIDER\nSECRET_KEY_BASE\n```\n\nHere are some default settings for provisioning a production server:\n\n```env\nLANG=en_US.UTF-8\nMALLOC_ARENA_MAX=2\nRACK_ENV=production\nRAILS_ENV=production\nRAILS_LOG_TO_STDOUT=enabled\nRAILS_SERVE_STATIC_FILES=enabled\nREDIS_PROVIDER=REDIS_URL\nPROTOCOL=https\n```\n\nThe `SECRET_KEY_BASE` environment variable is used to encrypt the passwords on your DM3 instance, so it is important to keep it secure and unguessable. Here's a good site for generating a secret key: https://www.grc.com/passwords.htm\n\nSet the `HOSTNAME` and `PROTOCOL` environment variables to the hostname and protocol of your Heroku application. For example, if your application is hosted at `https://my-project.herokuapp.com`, you would set the `HOSTNAME` variable to `my-project.herokuapp.com`, and the `PROTOCOL` variable to `https`.\n\nThe `EMAIL_FROM` environment variable is used for sending emails. This should be set to the email address you would like to appear in the \"From\" field in registration confirmation emails. \n\nIf you are using Postmark for emails, you must configure a Postmark transactional stream, go to its Settings, and choose \"authenticate with an SMTP Token\". You will use that token and the provided secret key as a username and password for the following environment variables:\n\n```env\nEMAIL_PORT=587\nEMAIL_SERVER=smtp.postmarkapp.com\nEMAIL_USERNAME=POSTMARK_SMTP_TOKEN\nEMAIL_PASSWORD=POSTMARK_SMTP_SECRET_KEY\n```\n\nIf you are using SendGrid for emails, you must go to your provisioned SendGrid account from the Heroku dashboard, and find the \"Settings\" \u003e \"API Keys\" section of the SendGrid service. Click the \"Create API Key\" button, copy the created key to the `EMAIL_PASSWORD` environment variable, and set the `EMAIL_USERNAME` environment variable to `apikey`. The other defaults for SendGrid are port 587 and server `smtp.sendgrid.net`. Note: some users have reported issues with SendGrid's spam filters trapping email notifications and not sending them forward. Using Postmark is therefore recommended.\n\n```env\nEMAIL_PORT=587\nEMAIL_SERVER=smtp.sendgrid.net\nEMAIL_USERNAME=apikey\nEMAIL_PASSWORD=SG.abcdefghijklmnopqrstuvwxyz\n```\n\nIf you are not using Postmark or SendGrid, these variables will need to be updated for whatever service you intend to use for outbound SMTP.\n\nBy default, the production environment will use AWS as the Active Storage service. This will require the following environment variables to be set:\n\n```\nAWS_ACCESS_KEY_ID\nAWS_BUCKET\nAWS_REGION\nAWS_SECRET_ACCESS_KEY\n```\n\nIt is possible use local storage, however this is only recommended for testing purposes, as Heroku does not have a persistent file system. This can be done by setting the `ACTIVE_STORAGE_SERVICE` variable to \"local\".\n\n### Set up database\n\nOnce these things are done, migrate the database using the following command:\n\n```\nheroku run rails db:migrate\n```\n\nDM3 should now be up and running on your Heroku instance! \n\nThe first user account created is automatically given admin powers. Thereafter, that user can grant other users access and privileges using the Admin menu in the top right corner of the interface. \n\nLocal installation\n-------------\n\n\n### With Docker Compose\n\nDM3 can be installed quickly using Docker Compose. The only requirements are [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) themselves.\n\nFirst, clone the repo from GitHub, `cd` into the repo directory, and copy the sample environment variables into `.env` and `config/application.yml`.\n\n```sh\ngit clone https://github.com/performant-software/dm-2.git\ncd dm-2\ncp .env.sample .env\ncp config/application.sample.yml config/application.yml\n```\n\n**Note**: In `.env`, when using Docker Compose, you must comment out the `REDIS_URL` environment variable.\n\nNext, there are slightly different instructions depending on whether you intend to run DM3 in a production or development environment.\n\n#### Development environment\n\nEdit `.env` as necessary. The sample values are all standard for a development environment, except for those left blank. `SECRET_KEY_BASE` should be a secure encryption key; variables beginning with `EMAIL_` should be configured to reflect your chosen SMTP server. For more information about these variables, see above section on [configuration variables](#configuration-variables).\n\nThen, use Docker Compose to build the necessary Docker images:\n```sh\ndocker-compose build\n```\n\nRun any pending database migrations:\n```sh\ndocker-compose run --rm app rails db:migrate\n```\n\nAnd finally, boot the application:\n```sh\ndocker-compose up\n```\n\nIf you wish to mount the code directory from your local filesystem onto the Docker container in order to develop on it, store local uploads, and use hot-reloading features, you can use the following command:\n```sh\ndocker-compose -f docker-compose.yml -f docker-compose.dev.yml up\n```\n\nAfter boot completes, the app should be up and running on `localhost:3000`.\n\nYou may stop the application at any time by opening another shell in the same `dm-2` directory and running:\n```sh\ndocker-compose down\n```\n\n#### Production environment\n\nEdit `.env` as necessary. In addition to those listed for the development environment, it is necessary to uncomment and set the variables listed under \"Required for production environments\" and \"Required for running Docker Compose in a production environment.\" The following are also required:\n\n```env\nRAILS_ENV=production \nRACK_ENV=production\nPROTOCOL=https\n```\n\nIt may also be necessary to configure Amazon S3 for Active Storage to function in production. See [below section on Active Storage](#active-storage).\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    Note about HTTPS and production\n  \u003c/summary\u003e\n\n  As you have set the three above variables to `production` and `https`, the app will be served from port 443 over HTTPS. \n\n  You will need a valid HTTPS certificate to run the app in production. You will likely also need to run Nginx with a reverse proxy, etc. to run from a hostname other than `localhost`. If you wish to run your app from `localhost` in production and use SSL certificates without a reverse proxy, you can follow [this guide](https://gist.github.com/tadast/9932075) and change `Procfile.prod` to match the `puma` command listed there. These configurations are outside the scope of this README.\n\n  It is **not recommended** and **not supported**, but if you wish to just get the app up and running quickly from `localhost`, you may change `/config/environments/production.rb:41` to `config.force_ssl = false`, and set `PROTOCOL` back to `http`. This is not secure, but will allow you to run the app over plain HTTP without a certificate. Local file upload and storage may fail with this configuration due to protocol differences.\n\u003c/details\u003e\n\nThen, use Docker Compose to build the necessary Docker images:\n```sh\ndocker-compose build\n```\n\nRun any pending database migrations using the `docker-compose.prod.yml` overrides:\n```sh\ndocker-compose -f docker-compose.yml -f docker-compose.prod.yml run --rm app rails db:migrate\n```\n\nAnd finally, boot the application in detached mode using the same overrides:\n```sh\ndocker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n```\n\nDuring boot, you may wish to view logs for the application:\n```sh\ndocker-compose logs -f -t\n```\n\nAfter boot completes, the app should be up and running on `localhost:443` (see above note about HTTPS and production).\n\nYou may stop the application at any time by opening another shell in the same `dm-2` directory and running:\n```sh\ndocker-compose down\n```\n\n### With Heroku local development environment\n\n#### Requirements\n\n- Ruby 3.3.2\n- Bundler 2.5.9+\n- PostgreSQL 16+\n- Node.js 16.x\n- Yarn 1.x\n- Redis 6+\n\n#### Setup\n\nDM3 is a Ruby on Rails 5.x/React application. Setting up PostgresSQL, Ruby, Bundler, Node.JS, Redis, and Yarn are beyond the scope of this README, but plenty of information is available online about these tools.\n\nEnsure that both PostgreSQL and Redis services are running.\n\nOnce the dependencies mentioned above are installed and running, please follow these steps:\n\n1) Clone this repo to your local drive:\n\n```sh\ngit clone https://github.com/performant-software/dm-2.git\n```\n\n2) Run bundler in the base directory to get all the Ruby dependencies:\n\n```sh\nbundle \n```\n\n3) Run yarn in the client directory to get all the JS dependencies:\n\n```sh\ncd client\nyarn\n```\n\n4) Create a database for the application. The default database is called \"DM3_staging\" with no username or password. You can configure this in the config/database.yml file. Once the database is created, run:\n\n```sh\nrails db:migrate\n```\n\n5) Run the server with the following command:\n\n```sh\nheroku local -f Procfile.dev\n```\n\nNote that this runs two servers, one on port 3000 for Ruby on Rails and one on 3001 for the Create React App yarn server. This hot reloads any changes made to the Javascript files as you develop.\n\n6) Visit http://localhost:3000 to view the application. \n\nPlease note that the development environment stores files on local disk in the /storage directory by default. You can configure different storage solutions in config/storage.yml. See the Rails Active Storage documentation for more details.\n\n### Manually\n\nInstallation without Docker or the Heroku toolset is possible but requires setup specific to your environment. Follow the steps given above, except when it comes time to run the application, run the client and the server with these commands:\n\nTo run the client:\n   \n```sh\ncd client \u0026\u0026 PORT=3000 yarn start\n```\n\nThen run the server:\n   \n```sh\nPORT=3001 \u0026\u0026 bundle exec puma -C config/puma.rb\n```\n\nFinally, run the task queue:\n\n```sh\nbundle exec sidekiq -e development -C config/sidekiq.yml\n```\n\nActive Storage\n-------------\n\nActive Storage is used to handle the uploading/downloading of files. Files can either be stored locally on the disk or on a file storage service, such as Amazon S3. For ease of toggling in different environments, the file storage service can be specified as an environment variable in the `application.yml` file.\n\n    ACTIVE_STORAGE_SERVICE: 'local'\n    ACTIVE_STORAGE_SERVICE: 'amazon'\n    \nTo convert an existing application to use a different file storage service, a rake task exists to downloading the files from the current storage and upload them to the new storage:\n\n    bundle exec rake active_storage:aws_to_local\n    bundle exec rake active_storage:local_to_aws\n\n\nUpgrade from 0.x\n-------------\n\nIn order to upgrade from 0.x to 1.0, please read the [upgrade guide in the DM3 wiki](https://github.com/performant-software/dm-2/wiki/v0.x-to-v1.0-upgrade-guide).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperformant-software%2Fdm-2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperformant-software%2Fdm-2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperformant-software%2Fdm-2/lists"}