{"id":50116801,"url":"https://github.com/severo/pelias-vagrant","last_synced_at":"2026-05-23T15:33:23.512Z","repository":{"id":352104327,"uuid":"208090311","full_name":"severo/pelias-vagrant","owner":"severo","description":"Create a VirtualBox machine with Pelias geocoder","archived":false,"fork":false,"pushed_at":"2026-04-17T21:19:43.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-17T23:29:24.366Z","etag":null,"topics":["brazil","docker","geocoder","pelias","vagrant","virtualbox"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/severo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2019-09-12T16:01:29.000Z","updated_at":"2026-04-17T21:19:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/severo/pelias-vagrant","commit_stats":null,"previous_names":["severo/pelias-vagrant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/severo/pelias-vagrant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severo%2Fpelias-vagrant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severo%2Fpelias-vagrant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severo%2Fpelias-vagrant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severo%2Fpelias-vagrant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/severo","download_url":"https://codeload.github.com/severo/pelias-vagrant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severo%2Fpelias-vagrant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33402165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"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":["brazil","docker","geocoder","pelias","vagrant","virtualbox"],"created_at":"2026-05-23T15:33:23.054Z","updated_at":"2026-05-23T15:33:23.505Z","avatar_url":"https://github.com/severo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pelias geocoder in a virtual box\n\nThis repository contains a Vagrant configuration to run the Pelias geocoder in a virtual machine.\n\n## Overview\n\nThe goal of this repository is to create a VirtualBox virtual machine that contains a working offline [Pelias](https://www.pelias.io/) geocoder.\n\nThe virtual machine is created using [Vagrant](https://developer.hashicorp.com/vagrant), from the [Vagrantfile](./Vagrantfile) provided in this repository.\n\nIf you want to use the Pelias geocoder for a different region, look at https://github.com/pelias/docker/tree/master/projects to find the region identifier, and adapt the environment variables accordingly.\n\nThe creation requires two steps:\n- one on the host machine to download and prepare the data,\n- and one to create the virtual machine and provision it with the Pelias geocoder and data.\n\n## Requirements\n\nThe instructions are for Ubuntu 25.10. Written on 15 April 2026.\n\nInstall VirtualBox:\n\n```bash\nsudo apt update\nsudo apt install virtualbox\n```\n\nInstall Vagrant (read https://developer.hashicorp.com/vagrant/install)\n\n```bash\nwget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?\u003c=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main\" | sudo tee /etc/apt/sources.list.d/hashicorp.list\nsudo apt update\nsudo apt install vagrant\n```\n\nEnsure that Vagrant is installed:\n\n```bash\nvagrant --version\nvagrant --help\n```\n\n\u003e [!IMPORTANT]\n\u003e Set the following environment variables, and ensure they are set during all the steps of this tutorial.\n\n```bash\n# Adapt to your needs\nexport PELIAS_PROJECT=portland-metro # smaller project. Try with it first, before trying with another region.\nexport PELIAS_DOCKER_DIR=~/tmp/docker\nexport VAGRANT_PROJECT_DIR=~/tmp/pelias-vagrant\n```\n\nGet the pelias/docker repository and create a symbolic link to the pelias command:\n\n```bash\n# get packages\nsudo apt update\nsudo apt install util-linux git curl\n\n# clone the repository and go to the project directory\nmkdir -p $PELIAS_DOCKER_DIR\ngit clone git@github.com:pelias/docker.git $PELIAS_DOCKER_DIR\nsudo rm -f /usr/local/bin/pelias\nsudo ln -s \"$PELIAS_DOCKER_DIR/pelias\" /usr/local/bin/pelias\n```\n\nGet this repository:\n\n```bash\nmkdir -p $VAGRANT_PROJECT_DIR\ngit clone git@github.com:severo/pelias-vagrant.git $VAGRANT_PROJECT_DIR\n```\n\n## Step 1: download and prepare the data on the host machine\n\nThe first step consists in preparing the data on the host machine. It's better to do this step before creating the virtual machine, because the host machine has more resources (CPU, RAM, disk space) than the virtual machine, and it will be faster to download and prepare the data.\n\nOn my machine (i9 32 cores, 64GB RAM, Ubuntu 25.10), the process takes about 10 minutes to download, prepare and import the data for the toy example 'portland-metro'. The longest step is the import into Elasticsearch.\n\nBy default, if you run the script, it will prepare the data for the \"portland-metro\" example:\n\n```bash\ncd ${PELIAS_DOCKER_DIR}/projects/${PELIAS_PROJECT}\n${VAGRANT_PROJECT_DIR}/host.sh\n```\n\nOnce done, for the portland-metro example, the ./data directory should contain the following subdirectories:\n\n```\n$ cd ${PELIAS_DOCKER_DIR}/projects/${PELIAS_PROJECT}; du -sh ./data/*\n4.0K    ./data/blacklist\n8.0K    ./data/csv\n1.3G    ./data/elasticsearch\n90M     ./data/interpolation\n11M     ./data/placeholder\n32M     ./data/transit\n5.2G    ./data/whosonfirst\n```\n\nThe logs are available for inspection:\n\n```\n$ cd ${PELIAS_DOCKER_DIR}/projects/${PELIAS_PROJECT}; du -sh *.log\n4.0K    host_1_init.log\n8.0K    host_2_download.log\n4.0K    host_3_prepare.log\n24K     host_4_import.log\n4.0K    host_5_clean.log\n60K     host_6_finish.log\n4.0K    host.log\n```\n\n```\n$ cat host.log\nStarting Pelias geocoder setup\nStep 1: initialization\nFri Apr 17 13:22:05 CEST 2026\nStep 2: download\nFri Apr 17 13:22:23 CEST 2026\nStep 3: prepare\nFri Apr 17 13:23:37 CEST 2026\nStep 4: import\nFri Apr 17 13:28:32 CEST 2026\nStep 5: clean\nFri Apr 17 13:32:08 CEST 2026\nStep 6: finish\nFri Apr 17 13:32:08 CEST 2026\nAll steps completed\nFri Apr 17 13:32:34 CEST 2026\n```\n\n### Tests\n\nAt this point, Pelias is running on your host machine. You can test that it's working by accessing the API:\n\n- http://localhost:4000/v1/search?text=portland\n- http://localhost:4000/v1/search?text=1901+Main+St\n- http://localhost:4000/v1/reverse?point.lon=-122.650095\u0026point.lat=45.533467\n- http://localhost:4100/demo/#eng\n- http://localhost:4200/-122.650095/45.533467\n- http://localhost:4300/demo/#13/45.5465/-122.6351\n- http://localhost:4400/parse?address=1730+ne+26th+ave,+portland,+or\n\nYou can also try https://pelias.github.io/compare, configuring the local geocoder with http://localhost:4000. Note that you can also run the compare tool locally, see https://github.com/pelias/compare.\n\nIf you try the following address:\n\n```\n6700 NE Prescott St, Portland, OR 97218, United States\n```\n\nPelias will return one point with the expected result, given by OpenAddresses: https://pelias.github.io/compare/#/v1/search?text=6700+NE+Prescott+St%2C+Portland%2C+OR+97218%2C+United+States\u0026debug=1\n\nFor the following address:\n\n```\n1955, Northwest Raleigh Street, Slabtown, Northwest District, Portland, Multnomah County, Oregon, 97209, USA\n```\n\nPelias gives 2 results with OpenAddresses and 3 results with OpenStreetMap, all with confidence 1 but not the same coordinates 🤷. Only two of them match the street number: https://pelias.github.io/compare/#/v1/search?text=1955%2C+Northwest+Raleigh+Street%2C+Slabtown%2C+Northwest+District%2C+Portland%2C+Multnomah+County%2C+Oregon%2C+97209%2C+USA\u0026debug=1\n\n### Detailed process\n\nOnce in the Portland project directory, and with the environment variables set, you can run the following commands to download the data, one at a time:\n\n```\npelias download wof\npelias download oa\npelias download osm # beware: it downloads an archive from 2022!\n```\n\nAt that point:\n\n```\n➜  portland-metro git:(master) ✗ du -sh data/*\n4.0K    data/blacklist\n41M     data/elasticsearch\n443M    data/openaddresses\n53M     data/openstreetmap\n5.2G    data/whosonfirst\n```\n\nThen prepare the data:\n\n```\npelias prepare polylines # only for OSM, creates data/polylines/extract.0sv\npelias prepare placeholder # only uses WOF? creates data/placeholder/store.sqlite3 and data/placeholder/wof.extract\npelias prepare interpolation # uses prepared polylines, then openadresses and openstreetmap, creates data/interpolation/address.db, data/interpolation/street.db and other temporary? files\n```\n\nAt that point:\n\n```\n➜  portland-metro git:(master) ✗ du -sh data/*\n4.0K    data/blacklist\n41M     data/elasticsearch\n114M    data/interpolation\n443M    data/openaddresses\n53M     data/openstreetmap\n17M     data/placeholder\n3.8M    data/polylines\n8.0K    data/tiger\n5.2G    data/whosonfirst\n```\n\nImport to Elasticsearch:\n\n```\npelias import wof\npelias import oa # \u003c- take some time (160s for Portland)\npelias import osm\npelias import polylines\n```\n\nThen start the containers:\n\n```\npelias compose up\n```\n\nThe running containers are:\n\n```\n➜  portland-metro git:(master) ✗ pelias compose ps\nNAME                   IMAGE                          COMMAND                  SERVICE         CREATED          STATUS          PORTS\npelias_api             pelias/api:master              \"./bin/start\"            api             42 seconds ago   Up 40 seconds   0.0.0.0:4000-\u003e4000/tcp\npelias_elasticsearch   pelias/elasticsearch:7.17.27   \"/bin/tini -- /usr/l…\"   elasticsearch   20 minutes ago   Up 20 minutes   127.0.0.1:9200-\u003e9200/tcp, 127.0.0.1:9300-\u003e9300/tcp\npelias_interpolation   pelias/interpolation:master    \"./interpolate serve…\"   interpolation   42 seconds ago   Up 40 seconds   127.0.0.1:4300-\u003e4300/tcp\npelias_libpostal       pelias/libpostal-service       \"/bin/wof-libpostal-…\"   libpostal       42 seconds ago   Up 40 seconds   127.0.0.1:4400-\u003e4400/tcp\npelias_pip-service     pelias/pip-service:master      \"./bin/start\"            pip             42 seconds ago   Up 40 seconds   127.0.0.1:4200-\u003e4200/tcp\npelias_placeholder     pelias/placeholder:master      \"./cmd/server.sh\"        placeholder     42 seconds ago   Up 40 seconds   127.0.0.1:4100-\u003e4100/tcp\n```\n\nand the logs should not contain errors:\n\n```\npelias compose logs\n```\n\n\n### Uninstall\n\nIf you want to uninstall and clean the data, you can run the following commands:\n\n```bash\n# assuming the current directory is the project directory (e.g. projects/portland-metro)\ncd ${PELIAS_DOCKER_DIR}/projects/${PELIAS_PROJECT}\npelias compose down\ngit restore .env\nrm ./*.log\nrm -rf ./data\n```\n\n## Step 2: create the virtual machine and provision it with the Pelias geocoder\n\nOnce step 1 is done, the data is ready and Pelias is running on your host machine. Ensure it's working before starting step 2.\n\nStep 2 is to create the virtual machine and provision it with the Pelias geocoder. The provisioning process will copy the data from the host machine to the virtual machine, and start the Pelias geocoder inside the virtual machine.\n\nRun the following command to create the virtual machine and provision it with the Pelias geocoder:\n\n```bash\nexport PELIAS_MACHINE_SIZE=\"20GB\" # adapt to your needs (at least 15GB for Pelias + the data), to ensure the data can be copied to the machine. The default value is 8GB, which is not enough for the \"portland-metro\" example.\nexport PELIAS_PORT=5000\ncd $VAGRANT_PROJECT_DIR\nvagrant up --provision\n```\n\nFor the \"portland-metro\" example, the provisioning process takes about 7 minutes, and the data copied to the virtual machine is about 6GB. The disk use is 17GB, including the 6GB of data.\n\n## Start the virtual machine\n\n\u003e [!IMPORTANT]\n\u003e The environment variables PELIAS_MACHINE_SIZE, PELIAS_DOCKER_DIR, PELIAS_PROJECT and PELIAS_PORT must be set before running any of the commands below.\n\nAny time you want to start the virtual machine, run:\n\n```bash\nvagrant up\n```\n\nSee status:\n\n```bash\nvagrant status\n```\n\nAccess the machine via SSH (no need to log in, as Vagrant takes care of that):\n\n```bash\nvagrant ssh\n```\n\nYou can also access the virtual machine directly via VirtualBox, and log in with the username \"vagrant\" and the password \"vagrant\".\n\n## Stop the virtual machine\n\n\u003e [!IMPORTANT]\n\u003e The environment variables PELIAS_MACHINE_SIZE, PELIAS_DOCKER_DIR and PELIAS_PROJECT must be set before running any of the commands below.\n\nTo stop the virtual machine, run:\n\n```bash\nvagrant halt\n```\n\n## Test the virtual machine\n\n\n- http://localhost:5000/v1/search?text=portland\n- http://localhost:5000/v1/search?text=1901+Main+St\n- http://localhost:5000/v1/reverse?point.lon=-122.650095\u0026point.lat=45.533467\n\n\nTODO: how to access these other services from :5000? See https://github.com/pelias/documentation?tab=readme-ov-file#endpoint-descriptions\n- http://localhost:4100/demo/#eng\n- http://localhost:4200/-122.650095/45.533467\n- http://localhost:4300/demo/#13/45.5465/-122.6351\n- http://localhost:4400/parse?address=1730+ne+26th+ave,+portland,+or\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsevero%2Fpelias-vagrant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsevero%2Fpelias-vagrant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsevero%2Fpelias-vagrant/lists"}