Skip to content

Running with Docker on any OS

Jump to bottom
Nikhil VJ edited this page Nov 14, 2018 · 9 revisions

"Docker" provides a way to run the program code in a self-contained container, irrespective of the operating system. Follow the steps below, with due variations depending on your OS.

Ref: this was set rolling by these issues posted on the repo: Packaging for Linux, Packaging for macOS. Give feedback, folks! Helps prioritize things.

Step Zero : Download this repo, and Install docker

Obviously 😄

Windows, .bat files

  • Double-click win_docker_install.bat to build and install for first time.
  • Double-click win_docker_run.bat to run the program.

Mac OS, .command files

  • Double-click MacOS_docker_install.command to build and install for first time.
  • In case the file doesn't execute, please set executable permissions on it. See this for help.
  • Double-click MacOS_docker_run.bat to run the program.

Ubuntu / Linux, .sh files

  • (Seriously? This is literally equivalent to running in a python virtual environment!)
  • Double-click and run docker_install.sh in terminal, one-time, to install.
  • Double-click and run docker_run.sh in terminal whenever you want to run it.

Via command line

Build

Get your Terminal / Command prompt to the program folder.

Run this command to "build" the docker application. You can think of this as an installation.
docker build -t static-gtfs-manager .

Note: don't miss the dot (.) at the end! That's for telling docker that the current directory is the source of the code.

It will take some time, especially if doing the first time. Screenshot: build

After that has happened, we can now run the application.

Run

On Mac or Ubuntu/Linux:

docker run -it -p 5000:5000 -v "`pwd`":/app static-gtfs-manager

On Windows:

docker run -it -p 5000:5000 -v "%cd%":/app static-gtfs-manager

Explanation of run command:

  • docker run -it : normal stuff
  • -p 5000:5000 : which port on your side will map to port 5000 of the program running in docker image. You can change the number on left side as per convenience.
  • -v "[present working directory]":/app : This is very important to make sure you don't lose all your work!
    • By default, docker runs with a "RAM" like memory (for Indian readers: Gajani!): the database, even though telling on front end that it's been saved and all, gets reset to "factory setting" every time we close the program and run it again.
    • The -v key tells it to keep a local persistent storage of all changes done. ie, the db changes written, are written through to your hard disk drive and don't just stay in RAM. (note: this is not a literal explanation, the details may vary)
    • The left side before the : tells that your program folder location is the place to do persistent storage at.
    • You can use another namespace instead of your program folder, like -v persistent:/app for example, but then where that data is located depends on the system installation, and it's up to you to make sure you don't lose your db suddenly. (issues posted in this regard will get a 'wontfix' label!)
    • The right side refers to the generic app location in the container. /app contains the whole program.
  • static-gtfs-manager : that's just a title. You can change it to use any title you want.

Troubleshooting

Port problems

  • port 5000 not available for some reason? No probs, you can map it to any other number in the docker run command itself.
  • If you're double-clicking a script (.bat / .command / .sh), just open your _run script in a text editor.
  • Change the left side of the numbers following -p key: docker run -it -p 5000:5000 ...
  • ..to a port number that's free on your system: docker run -it -p 8080:5000 ...

Opportunity for working with multiple feeds through docker

If running this tool in docker, users can keep multiple GTFS feeds or versions loaded through changing the label after -v in the run command. One can run the different versions simultaneously too by changing the left-side port number after -p for successive runs.

Note: Double-clickers : You may be better off getting down to command line for this. Don't be scared, it's still just one command for running the tool.

**Example: **

  • Operate on mumbai data: docker run -it -p 5000:5000 -v mumbai:/app "static-gtfs-manager"

  • Then, open a new terminal and operate on pune data: docker run -it -p 5001:5000 -v pune:/app "static-gtfs-manager"

  • Ignore the in-program URL shared; through docker you can now have two different instances of static-GTFS-Manager running in separate silos on http://localhost:5000 and http://localhost:5001 .

Explanation:

  • First command launches an instance of the program with local storage in a folder (somewhere up in the system folders) called mumbai. So all db changes there get saved to mumbai. And not even your local program folder.
  • Second command launches another instance, with local storage in a separate folder called pune.
  • The 5001:5000 port mapping in second command makes that instance run on another URL, so you can operate both instances at the same time. They'll both work in their own separate silo's now.

Googly
You know what? If running this directly from python or windows exe or linux executable, you can simply make copies of your static-GTFS-manager program folder and do different business from different folders 😆

Docker housekeeping

  • You can list the volumes created with this command: docker volume ls.
  • To see a list of commands, do docker volume
  • To manually browse these, open this path in a file browser with root permissions: /var/lib/docker/volumes
  • List of docker images installed on your system: docker images
  • List of containers (so one image can have multiple instances so containers): docker ps -a (note: -a will also list expired sessions)
  • Prune out the excess stuff: docker system prune see explanation
  • Disclaimer: export your db, take backups before doing any of this, esp if your -v local volume isn't the local program folder but a different namespace like mumbai or pune in the examples above. You might lose ALL your work if the housekeeping throws the baby out with the bathwater.
  • More info: see bottom parts of this article on runnable.com
Clone this wiki locally