{"id":21893257,"url":"https://github.com/fieldpapers/fp-web","last_synced_at":"2025-09-12T12:36:14.876Z","repository":{"id":27205445,"uuid":"30676165","full_name":"fieldpapers/fp-web","owner":"fieldpapers","description":"Field Papers web app","archived":false,"fork":false,"pushed_at":"2025-09-04T21:50:56.000Z","size":6246,"stargazers_count":21,"open_issues_count":11,"forks_count":20,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-09-04T23:31:01.698Z","etag":null,"topics":["fieldpapers","hacktoberfest","openstreetmap","ruby"],"latest_commit_sha":null,"homepage":"https://fieldpapers.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fieldpapers.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-02-11T23:51:30.000Z","updated_at":"2025-08-04T17:39:37.000Z","dependencies_parsed_at":"2024-04-18T19:33:24.557Z","dependency_job_id":"dc190a55-138a-4a2a-b3f9-1e1a30805291","html_url":"https://github.com/fieldpapers/fp-web","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fieldpapers/fp-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fieldpapers%2Ffp-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fieldpapers%2Ffp-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fieldpapers%2Ffp-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fieldpapers%2Ffp-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fieldpapers","download_url":"https://codeload.github.com/fieldpapers/fp-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fieldpapers%2Ffp-web/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273775409,"owners_count":25165839,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"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":["fieldpapers","hacktoberfest","openstreetmap","ruby"],"created_at":"2024-11-28T13:13:09.430Z","updated_at":"2025-09-12T12:36:14.846Z","avatar_url":"https://github.com/fieldpapers.png","language":"Ruby","readme":"# Field Papers\n\n## Quick links\n- [🔗 fieldpapers.org](https://fieldpapers.org)\n- [📋 Project overview](https://github.com/fieldpapers)\n- [🐞 Issues and bug reports](https://github.com/fieldpapers/fieldpapers/issues)\n- [🌐 Translations](https://explore.transifex.com/fieldpapers/fieldpapers/)\n- [🤝 Code of Conduct](https://wiki.openstreetmap.org/wiki/Foundation/Local_Chapters/United_States/Code_of_Conduct_Committee/OSM_US_Code_of_Conduct)\n\n## Development\n\n### Setting environment variables\n\nThe following is required to run Field Papers, whether locally or via Docker / `docker-compose`:\n\n```bash\ncp sample.env .env\n# provide some AWS credentials, etc.\nopen -t .env\n```\n\nIn the opened text editor, add variables per [Environment Variables](https://github.com/fieldpapers/fp-web#environment-variables). Contact another Field Papers contributor for any required values not present in `sample.env`.\n\n### Using docker-compose\n\n[compose](https://docs.docker.com/compose/) is\na [Docker](https://www.docker.com/)-based tool for orchestrating development\nenvironments. Rather than using `foreman` to manage multiple processes locally,\n`compose` runs each component process in a separate container, built up from\nlocal `Dockerfile`s or from remote repositories.\n\n#### Prerequisites\n\n* A working instance of [Docker](https://www.docker.com/), via\n  [boot2docker](https://boot2docker.io/), [docker\n  machine](https://docs.docker.com/machine/), or another mechanism\n* mDNS, built-in on OS X, via `libnss-mdns` on Linux or [Bonjour Print Services\n  fpr Windows](https://support.apple.com/kb/DL999?locale=en_US)\n* [Docker compose](https://docs.docker.com/compose/)\n\n#### Starting\n\nThis will fetch and build images as appropriate, logging `STDOUT` from all containers.\n\n```bash\ndocker-compose build\n```\n\nIf this is the first time you're running this, you'll need to load the schema into MySQL:\n\n```bash\ndocker-compose run web rake db:schema:load\n```\n\nIf you have pending migrations, run:\n\n```bash\ndocker-compose run web rake db:migrate\n```\n\nTo start the stack, logging `STDOUT` from all containers:\n\n```bash\ndocker-compose up\n```\n\nThe app will now be running on port 3000 on the Docker host. If you're lucky, it will be available\nat [`docker.local:3000`](https://docker.local:3000), otherwise you'll need to determine the IP of\nyour Docker host (`localhost` on Linux) and use that in place of `docker.local`.\n\nIf `docker.local` doesn't work, you'll need to update `docker-compose.yml` to set `TILE_BASE_URL`\n(in the `environment` section of `web`) to reflect your Docker host's IP. In my case, it's\n`192.168.64.6`. You should be able to determine appropriate values using:\n\n```bash\ndocker-compose port web 8080\n```\n\nNote, adding system dependencies to the `Dockerfile` requires you to\n`docker-compose build` in order to recreate the base `web` image.\nIf you've just made changes to `Gemfile`, run `docker-compose run web bundle`.\n\n\nSome helpful `docker` and `docker-compose` commands to know:\n\n0. To get a list of docker images ( and versions ) that the containers are running:\n\n    ```bash\n    $ docker images\n    REPOSITORY                  TAG                 IMAGE ID            CREATED             VIRTUAL SIZE\n    fpweb_web                   latest              e2cafa474299        58 minutes ago      940.4 MB\n    quay.io/fieldpapers/tiler   v0.2.0              b2683b4d606d        3 days ago          855.9 MB\n    mysql                       latest              c607d9b50dfa        13 days ago         374.1 MB\n    ruby                        2.2.4               9168c99105ac        2 weeks ago         719.3 MB\n    quay.io/fieldpapers/tasks   v0.10.2             f637d9257755        8 weeks ago         843 MB\n    ```\n\n0. To see a list of the containers and their state that are running under `docker-compose`:\n\n    ```bash\n    $ docker-compose ps\n        Name                   Command               State                       Ports\n    -------------------------------------------------------------------------------------------------------\n    fpweb_db_1      docker-entrypoint.sh mysqld      Up      3306/tcp\n    fpweb_tasks_1   /bin/sh -c npm start             Up\n    fpweb_tiler_1   /bin/sh -c npm start             Up\n    fpweb_web_1     /bin/sh -c rm -f tmp/pids/ ...   Up      0.0.0.0:3000-\u003e3000/tcp, 0.0.0.0:8080-\u003e8080/tcp\n    ```\n\n\n### Running Locally\n\nGiven the potential complexity of the above, or the need to make changes to the\nperipheral services, it may make more sense to run the application locally (you\ncan still use `docker-compose` to run supplementary services like MySQL, etc.).\nIf not using `docker-compose`, be sure MySQL is installed (`$``brew install mysql`\nif not) and running (`$``mysql.server start` if not).\n\nOn OS X, you'll want to use `rbenv` (and `ruby-build`) in order to isolate the\nversion of Ruby used here (and to prevent it from conflicting with other\nprojects). `bundler` is similarly used to localize gem dependencies.\n\n[`direnv`](https://github.com/zimbatm/direnv) is a handy way to set\nproject-specific environment variables (such as `PATH` or `DATABASE_URL`).\nA default `.envrc` has been provided that adds `bin/` to your `PATH`\n(`$(pwd)/bin`, technically, to prevent abuse) so that bundler binstubs can be\nused. It's opt-in, so you'll need to enable it with `direnv allow .`.\n\nGhostscript is used to merge atlas pages together into a single PDF, so you'll\nneed that (and `boot2docker` generate individual pages) to generate atlases.\n\n#### OS X\n\n```bash\nbrew install rbenv ruby-build direnv ghostscript boot2docker\n\nboot2docker init         # create the Docker host if necessary\nboot2docker up           # start the Docker host\n$(boot2docker shellinit) # set the necessary Docker environment vars\n\neval \"$(rbenv init -)\"     # initialize rbenv\neval \"$(direnv hook bash)\" # initialize direnv\nrbenv install $(\u003c .ruby-version) # install the desired ruby version\n\ngem install bundler        # install bundler using rbenv-installed ruby\n\nxcode-select --install     # install Xcode command line utilities\n\n# on 10.11, openssl headers aren't easily findable\nbundle config build.eventmachine --with-opt-dir=/usr/local/opt/openssl\n\nbundle install -j4 --path vendor/bundle # install dependencies\n\ndirenv allow .             # whitelist the local .envrc\n\necho $DATABASE_URL         # ensure that your environment is prepared\n\nrake db:create             # create a database if one doesn't already exist\nrake db:schema:load        # initialize your database\n\nrails server -b 0.0.0.0 # start the app, listening on all interfaces\n```\n\n#### Ubuntu\n\n[Install Docker](https://docs.docker.com/installation/ubuntulinux/).\n\n```bash\nsudo apt-get install ghostscript git-core curl zlib1g-dev \\\n  build-essential libssl-dev libreadline-dev libyaml-dev \\\n  libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev \\\n  python-software-properties libffi-dev\n\n# install rbenv + ruby-build\ngit clone git://github.com/sstephenson/rbenv.git ~/.rbenv\necho 'export PATH=\"$HOME/.rbenv/bin:$PATH\"' \u003e\u003e ~/.bash_profile\necho 'eval \"$(rbenv init -)\"' \u003e\u003e ~/.bash_profile\n\ngit clone git://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build\necho 'export PATH=\"$HOME/.rbenv/plugins/ruby-build/bin:$PATH\"' \u003e\u003e ~/.bash_profile\nsource ~/.bash_profile\n\neval \"$(direnv hook bash)\" # initialize direnv\nrbenv install $(\u003c .ruby-version) # install the desired ruby version\n\ngem install bundler        # install bundler using rbenv-installed ruby\n\nbundle install -j4 --path vendor/bundle # install dependencies\n\ncp sample.env .env\nsensible-editor .env\n\nbundle exec foreman run echo $DATABASE_URL # ensure that your environment is prepared\n\nrake db:create             # create a database if one doesn't already exist\nrake db:schema:load        # initialize your database\n\nbundle exec foreman run rails server -b 0.0.0.0 # start the app, listening on all interfaces\n```\n\nThe app will now be running on [localhost:3000](https://localhost:3000/) and\nwill also be available as `\u003cyou\u003e.local` (which is what should be used for\n`BASE_URL`).\n\nYou'll probably want to add the following to the end of your `.bash_profile`\n(or equivalent):\n\n```bash\nif which rbenv \u003e /dev/null; then eval \"$(rbenv init -)\"; fi`\neval \"$(direnv hook bash)\"\n```\n\nIf you choose not to use `direnv`, you'll need to ensure that the contents\nof `.env` are exported in your environment.\n\n[foreman](https://github.com/ddollar/foreman) is an alternative, in which\ncase you'll prefix all commands with `foreman run \u003ccmd\u003e` in order to expose\nenvironment variables to them.\n\nBarring that, `export \u003cVAR\u003e=\u003cVAL\u003e` for each pair in each shell instance\nyou're using.\n\nWhen updating, the following should be sufficient to sync your working copy:\n\n```bash\nbundle\nrake db:migrate RAILS_ENV=development\n```\n\nThere are probably additional Homebrew dependencies I'm missing because they\nwere already installed.\n\nNOTE: If you later decide to use `fig`, you'll need to delete `vendor/bundle`\nfirst.\n\n### Environment Variables\n\nIf using `direnv` or `foreman`, add these to `.env`. Otherwise, ensure that\nthey are available to the environment in which Rails is running.\n\n* `DATABASE_URL` - development database URL. Probably similar to\n  `mysql2://root@localhost/fieldpapers_development`\n* `TEST_DATABASE_URL` - test database URL.\n* `RDS_DB_NAME` - production database name.\n* `RDS_HOSTNAME` - production database hostname.\n* `RDS_PASSWORD` - production database password.\n* `RDS_PORT` - production database port.\n* `RDS_USERNAME` - production database username.\n* `MAIL_ORIGIN` - From address to use for automated system emails.\n* `MAIL_SOURCE_ARN` - AWS SES mail source identity. (Associated credentials must\n  be granted access to send from this)\n* `BASE_URL` - Site base URL (Network-accessible, i.e. from a Docker container).\n* `S3_BUCKET_NAME` - S3 bucket for file storage. Required. Some endpoints might be\n  `dev.files.fieldpapers.org` (development), `test.files.fieldpapers.org`\n  (test), and `files.fieldpapers.org` (production).\n* `AWS_ACCESS_KEY_ID` - AWS key with read/write access to the configured S3\n  bucket(s).\n* `AWS_SECRET_ACCESS_KEY` - Corresponding secret.\n* `AWS_REGION` - AWS region to use for services.\n* `BASE_URL` - Base URL, e.g. `https://fieldpapers.org`.\n* `TASK_BASE_URL` - Base URL for the task server (probably an instance of\n  [fp-tasks](https://github.com/fieldpapers/fp-tasks)).\n* `TILE_BASE_URL` - Base URL for the snapshot tiler (probably an instance of\n  [fp-tiler](https://github.com/fieldpapers/fp-tiler)).\n* `SENTRY_DSN` - Sentry DSN for exception logging. Optional.\n* `MAPZEN_SEARCH_KEY` - A Mapzen Search API key, obtained from\n  [mapzen.com/developers](https://mapzen.com/developers).\n* `STATIC_PATH` - Path to write static files to. Must be HTTP-accessible.\n  Defaults to `./public`.\n* `STATIC_URI_PREFIX` - Prefix to apply to static paths (e.g.\n  https://example.org/path) to allow them to resolve. Defaults to `BASE_URL`.\n* `PERSIST` - File persistence. Can be `local` or `s3`. Defaults to `s3`.\n* `DEFAULT_CENTER` - Default center for atlas composition (when a geocoder is\n  unavailable). Expected to be in the form `\u003czoom\u003e/\u003clatitude\u003e/\u003clongitude\u003e`.\n  Optional.\n* `ATLAS_COMPLETE_WEBHOOKS` - A comma separated string of URLs. Optional. When an atlas\n  moves to the state 'complete', fp-web will `POST` the JSON representation\n  of the atlas to each URL.\n* `ATLAS_INDEX_HEADER_TILELAYER` - A [Leaflet TileLayer urlTemplate](https://leafletjs.com/reference.html#tilelayer). Optional.\n  Providing this url will override the header basemaps for the atlas index pages. Defaults to `https://{S}.tile.openstreetmap.org/{Z}/{X}/{Y}.png`\n* `DISABLE_LOGIN_CONFIRMATIONS` - A value of `true` will not require\n  users to confirm their accounts after registration and will not send confirmation emails.\n  Optional. Defaults to `false` -- registration confirmations are required\n\n### Running Tests\n\n```bash\nrake\n```\n\nAlternately, you can use [Guard](https://github.com/guard/guard) to\nautomatically run tests when related files change:\n\n```bash\nguard\n```\n\n### Translation and Localization\n\nTo mark a string as one that should be localized, wrap it in `_()`.\n\nE.g. in an ERB template,\n\n`\u003c% content_for :title, \"Atlas - Field Papers\" %\u003e`\n\nbecomes\n\n`\u003c% content_for :title, _(\"Atlas - Field Papers\") %\u003e`.\n\nE.g. in Javascript within an ERB template,\n\n`window.alert(\"Hello Field Papers!\")`\n\nbecomes\n\n`window.alert(_('\u003c%=escape_javascript _(\"Hello Field Papers!\") %\u003e'))`.\n\nInstall the [Transifex](https://www.transifex.com/) client (`tx`):\n\n```bash\n# optionally create a virtualenv\nvirtualenv venv\nsource venv/bin/activate\n\n# install Python dependencies\npip install -r requirements.txt\n```\n\nTo extract strings from the app (and update pending translations):\n\n```bash\nrake gettext:find\n```\n\nTo see the current translation status:\n\n```bash\ntx status\n```\n\nTo push updated strings:\n\n```bash\ntx push -s\n```\n\nWhile it's possible to push updated translations, don't; Transifex is the\nsource of truth for non-English strings.\n\nTo pull pending translations:\n\n```bash\ntx pull -af\n```\n\nTo initialize a new language:\n\n```bash\nlocale=es\nmkdir -p locale/${locale}\ncp locale/en/* locale/${locale}/\ntx set -r fieldpapers.www -l ${locale} locale/${locale}/app.po\n```\n\nYou'll also need to add the new locales to\n`config/initializers/fast_gettext.rb` and to the footer\n(`app/views/shared/_footer.html.erb`).\n\n### Heroku Deployment\n\nDue to the presence of both `Gemfile` and `requirements.txt`, Heroku reports\nthe ability to build this app using both the Ruby and Python buildpacks. The\ncurrent [buildpack detection\norder](https://devcenter.heroku.com/articles/buildpacks#buildpack-detect-order)\nputs Ruby first, but explicit is better than implicit, so you can force the\nRuby buildpack to be used:\n\n```bash\nheroku buildpack:set https://github.com/heroku/heroku-buildpack-ruby\n```\n\n### Data\n\nTo bootstrap a database for development or on a new instance, run:\n\n```bash\nrake db:create db:schema:load\n```\n\nBy default, it will create a `fieldpapers_development` (and `fieldpapers_test`)\ndatabase on a local MySQL instance. To override this, set `DATABASE_URL` (in\nyour environment, either directly or via `.env`), e.g.:\n\n```bash\nDATABASE_URL=mysql2://vagrant@somewhere/fieldpapers_development\n```\n\nTo migrate an existing Field Papers database, first back it up. Then, set\n`DATABASE_URL` to point to it and run (with an appropriate `RAILS_ENV` if\nneeded):\n\n```bash\nrake db:migrate\n```\n\nThis will produce a database schema that is no longer compatible with the PHP\nversion. Part of the migration involves cleaning up encoding errors (UTF-8 text\nstored as latin1 in UTF-8 columns)--your database may include some invalid\ncharacters, causing the migration to fail. To work-around that, identify the\naffected rows and clear their values before retrying the migration.\n\n\n### AWS Deployment\n\nThe Rails `production` environment is set up to allow a \"quick start\"\ndeployment on Amazon Web Services using the [`aws-quick-start.py`\nscript](https://github.com/fieldpapers/fieldpapers/blob/master/aws-quick-start/aws-quick-start.py)\nin the\n[`fieldpapers/fieldpapers` repository](https://github.com/fieldpapers/fieldpapers).\nSee the documentation\n[here](https://github.com/fieldpapers/fieldpapers/tree/master/aws-quick-start)\ndetails.\n\nA couple of things to note about this production environment:\n\n * The database configuration (in `config/database.yaml`) is taken\n   from a set of `RDS_*` environment variables which are set up\n   automatically by AWS within the Docker container where the Rails\n   web app runs.  The AWS Relational Database Service (RDS) database\n   is set up automatically by the `aws-quick-start.py` script.\n\n * Access to AWS resources (the S3 bucket used to store atlas pages\n   and snapshots, the database, the SES mail service) is managed using\n   AWS Identity and Access Management (IAM) roles, policies and\n   instance profiles.\n\n * Obviously the relevant IAM roles, policies and instance profiles\n   have to exist with the appropriate permissions.  The easiest (and\n   only recommended) way to do this is to use the `aws-quick-start.py`\n   script to set everything up.  It's kind of complicated and there\n   are no guarantees that it will work if you try to do it by hand...\n\n * No AWS credentials appear anywhere in the code and no credentials\n   are loaded from environment variables (such as `AWS_ACCESS_KEY_ID`\n   or `AWS_SECRET_ACCESS_KEY`) when running on an EC2 instance;\n   instead, temporary AWS credentials are made available by the\n   infrastructure on the EC2 instance and are accessed via the\n   instance metadata (the Ruby AWS SDK deals with this transparently).\n\n * There are some cases where extra authentication information is\n   required to perform AWS actions from within an EC2 instance.  In\n   particular, a session token is needed to validate temporary AWS\n   credentials (a case handled transparently by the AWS Ruby SDK), and\n   a \"source ARN\" is required for sending email (which needs to be\n   handled explicitly).  This source ARN is needed to associate the\n   EC2 instance with a mail identity policy so that the web app can\n   send email using the AWS SES email service.\n\n\n#### Extra environment variables\n\nThese are all set up by the `aws-quick-start.py` script, but are\ndocumented here for reference.  They should *not* need to be set\nexplicitly!\n\n* `MAIL_ORIGIN` - the originating email address used for sending\n  account confirmation, password reset, etc. emails.\n* `MAIL_SOURCE_ARN` - AWS resource identifier used to associate EC2\n   instance with a mail identity policy, allowing email to be sent\n   from within an EC2 instance using the AWS Simple Email Service\n   (SES).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffieldpapers%2Ffp-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffieldpapers%2Ffp-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffieldpapers%2Ffp-web/lists"}