Running the Mapnik Server on VS Code

How to setup a development environment for the Treetracker API in VS Code

Software Needed

• Visual Studio Code => https://code.visualstudio.com/

  • Docker Extension: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

  • Remote Explorer Extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

• Docker Desktop => https://www.docker.com/products/docker-desktop

Environment Setup

Install Visual Studio Code (VS Code) and Docker Desktop. Once installations are complete, make sure Docker Desktop is running (this is initiated by opening Docker Desktop - once it is running you will see it appear in your menu bar).

Once VS Code is installed, install the Docker and Remote Explorer extensions. You can download these by visiting the links above or by searching for them in the extensions tab.

By default, the Docker extension will automatically remove the container once you are done using it, so we must first edit some extension configurations so that we can persist our work across sessions:

• Navigate to your extensions tab and click on the gear icon that appears over the Docker extension, then select Extension Settings

• Under any of the settings, select Edit in settings.json

  • Add the following to your settings.json

    "docker.commands.run": "docker run -d ${exposedPorts} ${tag}",
    "docker.commands.runInteractive": "docker run -it ${exposedPorts} ${tag}"

Open the Dockerfile for the node-mapnik repo and make the following changes:

# CMD [ "npm", "start" ]

Comment out the last line in the Dockerfile in order to prevent the development server automatically running inside the container. Being able to independently run the server allows the developer to see the output from the mapnik server.

Now inside the file explorer, right click on the Dockerfile that was just edited and select Build Image You must have Docker Desktop running in order for this step to work.

Select a name for your image then VS Code will create the image.

Once that is complete, you can find all the built Docker images in your system inside the Docker extension panel, listed in the images section. Right click on the image you just built and select Run Interactive

Navigate to the Remote Explorer Extension panel and and find the container running the image. Right click on the container and select Attach to Container or Attach in New Window if you would like VS Code to open a new window.

This will integrate VS Code with the environment of the Docker container. Once you are connected, your editor window will most likely look like this:

Click on Open Folder, then navigate to the app/ folder. You will most likely start in the /root/ folder, in which case you need to move one directory up by first selecting .. then selecting app/

Click 'OK' and you should see the file structure load with the latest master version of the repository (but you can ensure this by running a git pull in the terminal).

Run the development server with npm start. In order to have a proper connection to the database, you will need to include the connection string.

DB_URL=postgresql://<username>:<password>@<host>:<port>/treetracker_dev?ssl=true npm start

In order to interact with the API in your native browser, you will need to map the Docker container's port to one of the ports that is available on your machine. This will be done by default by VS Code, but it may not work, in which case perform the following steps:

Remove the auto forwarded port bind by clicking on the X that appears next to it.

Then add a port yourself and type the port number that the development server is running on (should be 23300 by default). If this port is already occupied on your native machine, you will need to change the local address to localhost:<some_other_port_num>.

Navigate to your browser and try accessing the local address and interacting with the API.

Note

In order to avoid git issues, I would recommend copying and pasting all changes made inside the container to your local file system, then pushing your local changes to your branch/fork. Afterwards, make a pull request to the main Greenstand node-mapnik repo.

By default, the global Github user of the container is Dadior's, so if you push changes from the container, Dadior may be credited as the author. You can change the user, but ever since Github moved to 2-factor authentication, I haven't found a clean way of logging in through the command line. There is also a possibility that the container will not persist your Github account changes and will revert the next time you run the container.

If you have any questions, feel free to reach out to me (Kaushal Parikh) or Dadior Chen on Slack, or send a message in any of the engineering channels.