{"id":13638748,"url":"https://github.com/robertcsapo/cisco-meraki-cmx-api-app","last_synced_at":"2025-04-19T21:34:42.816Z","repository":{"id":139954375,"uuid":"62513975","full_name":"robertcsapo/cisco-meraki-cmx-api-app","owner":"robertcsapo","description":"Cisco Meraki CMX API demo app - as a Docker Container","archived":true,"fork":false,"pushed_at":"2017-10-29T08:01:56.000Z","size":1038,"stargazers_count":7,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-09T09:37:56.359Z","etag":null,"topics":["cisco","cmx","cmx-api","docker","meraki"],"latest_commit_sha":null,"homepage":"http://developers.meraki.com/tagged/Location","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robertcsapo.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}},"created_at":"2016-07-03T20:28:27.000Z","updated_at":"2023-01-28T05:46:24.000Z","dependencies_parsed_at":"2024-02-09T08:47:14.329Z","dependency_job_id":null,"html_url":"https://github.com/robertcsapo/cisco-meraki-cmx-api-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcsapo%2Fcisco-meraki-cmx-api-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcsapo%2Fcisco-meraki-cmx-api-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcsapo%2Fcisco-meraki-cmx-api-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcsapo%2Fcisco-meraki-cmx-api-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robertcsapo","download_url":"https://codeload.github.com/robertcsapo/cisco-meraki-cmx-api-app/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249811063,"owners_count":21328742,"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","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":["cisco","cmx","cmx-api","docker","meraki"],"created_at":"2024-08-02T01:00:52.857Z","updated_at":"2025-04-19T21:34:42.534Z","avatar_url":"https://github.com/robertcsapo.png","language":"Ruby","funding_links":[],"categories":["Location"],"sub_categories":["Contents"],"readme":"# Cisco Meraki CMX API demo app - as a Docker Container\n\nThis application show you how to get started using the [Cisco Meraki](https://meraki.cisco.com/) CMX API.  \nCMX (Connected Mobile Experiences) is Cisco’s location analytics and engagement platform, and it’s integrated into Cisco Meraki wireless products.  \nTo learn more about what you can do with CMX, see the [Cisco Meraki CMX site](https://meraki.cisco.com/solutions/cmx) and at [Cisco Meraki Developers](http://developers.meraki.com/tagged/Location)  \n  \nForked https://github.com/meraki/cmx-api-app and merged Readme.  \n  \n![](https://raw.githubusercontent.com/robertcsapo/cisco-meraki-cmx-api-app/master/meraki-cmx-api-app-docker.gif)\n\n## Table of contents\n\n- [Network infrastructure requirements](#network-infrastructure-requirements)\n- [Setting up the Cisco Meraki Dashboard](#setting-up-the-cisco-meraki-dashboard)\n- [Starting docker container](#interactive-with-output-to-tty)\n- [Sample output code](#sample-output-code)\n- [Copyright and license](#copyright-and-license)\n\n## DISCLAIMERS:\n\n1. This code is for sample purposes only. Before running in production,\n   you should probably add SSL/TLS support by running this server behind a\n   TLS-capable reverse proxy like nginx.\n\n2. You should also test that your server is capable of handling the rate\n   of events that will be generated by your networks. A good rule of thumb is\n   that your server should be able to process all your network's nodes once per\n   minute. So if you have 100 nodes, your server should respond to each request\n   within 600 ms. For more than 100 nodes, you will probably need a multithreaded\n   web app.\n\n## Network infrastructure requirements\n\n- The app requires using one or more [Cisco Meraki MR wireless access points](https://meraki.cisco.com/products/wireless) (APs).\n- A valid license is required for each Meraki AP.\n- Note: this app does not work with other Cisco APs or non-Cisco APs.\n\n## Setting up the Cisco Meraki Dashboard\nLet’s say you plan to run this app on a docker host you control called pushapi.myserver.com.\n\n1. Go to the Cisco Meraki dashboard and configure the CMX API (find it under Network-wide \u003e Configure \u003e General) with the url `http://pushapi.myserver.com:4567/events`\n2. Choose a secret and enter it into the dashboard.\n3. Make note of the validation code that dashboard provides.\n4. Pass the secret (red box) and validation code (green box) to your docker container when you start it - [Starting docker container](#interactive-with-output-to-tty)  \n![](https://raw.githubusercontent.com/robertcsapo/cisco-meraki-cmx-api-app/master/meraki-cmx-api-app-screenshot.png)\n\n## Docker host\n\n### Interactive with output to tty\n- Start your app by running this interactive container to show output\n```\ndocker run --rm -it -p 4567:4567 \\\n-e CMX_SECRET=secret \\\n-e CMX_VALIDATOR=validator \\\nrobertcsapo/cisco-meraki-cmx-api-app\n```\n\n- If you want to use another port then 4567\n```\ndocker run --rm -it -p 80:80 \\\n-e CMX_SECRET=secret \\\n-e CMX_VALIDATOR=validator \\\n-e CMX_PORT=80 \\\nrobertcsapo/cisco-meraki-cmx-api-app\n```\n\n- If you want to bind your server to a certain ip-address of the host\n```\ndocker run --rm -it -p 4567:4567 \\\n-e CMX_BIND=0.0.0.0 \\\n-e CMX_SECRET=secret \\\n-e CMX_VALIDATOR=validator \\\n--net=host robertcsapo/cisco-meraki-cmx-api-app\n```\n\n### Running it as daemon\n```\ndocker run -d -p 4567:4567 \\\n-e CMX_SECRET=secret \\\n-e CMX_VALIDATOR=validator \\\nrobertcsapo/cisco-meraki-cmx-api-app\n```\n- Accessing the container when running as daemon\n```\ndocker exec -it \u003ccontainerid/containername\u003e /bin/bash\n```\n\n### Build container from scratch\n\n- git clone https://github.com/robertcsapo/cisco-meraki-cmx-api-app.git\n- ```docker build -t robertcsapo/cisco-meraki-cmx-api-app .```\n\n### ciscoshipped.io\nIt's now possible to host this application through ciscoshipped.io.  \n[README.md](https://github.com/robertcsapo/cisco-meraki-cmx-api-app/tree/master/ciscoshipped) in ciscoshipped folder.  \n\n## Validate the docker service in Meraki Dashboard\n\n- Click the “Validate server” button in CMX Location Push API configuration in\nthe dashboard. Meraki cloud servers will perform a GET to your server, and you will\nsee a log message like this:  \n```[26/Mar/2014 11:52:09] \"GET /events HTTP/1.1\" 200 6 0.0024```\n\n- If you do not see such a log message, check your firewall and make sure\nyou’re allowing connections to port 4567. You can confirm that the server\nis receiving connections on the port using  \n```telnet pushapi.myserver.com 4567```\n\n- Once the Meraki cloud has confirmed that the URL you provided returns the expected\nvalidation code, it will begin posting events to your URL. For example, when\na client probes one of your access points, you’ll see a log message like\nthis:  \n```\n[2014-03-26T11:51:57.920806 #25266]  INFO -- : AP 11:22:33:44:55:66 on [\"5th Floor\"]: {\"ipv4\"=\u003e\"123.45.67.89\", \"location\"=\u003e{\"lat\"=\u003e37.77050089978862, \"lng\"=\u003e-122.38686903158863,\"unc\"=\u003e11.39537928078731}, \"seenTime\"=\u003e\"2014-05-15T15:48:14Z\", \"ssid\"=\u003e\"Cisco WiFi\",\"os\"=\u003e\"Linux\", \"clientMac\"=\u003e\"aa:bb:cc:dd:ee:ff\",\"seenEpoch\"=\u003e1400168894, \"rssi\"=\u003e16, \"ipv6\"=\u003enil, \"manufacturer\"=\u003e\"Meraki\"}\n```\n\n- After your first client pushes start arriving (this may take a minute or two),\nyou can get a JSON blob describing the last client probe (where {mac} is the client mac address): `pushapi.myserver.com:4567/clients/{mac}`\n\n- You can also view the sample frontend at: `http://pushapi.myserver.com:4567/`.  \nTry connecting your mobile device to your network, and entering your mobile device‘s WiFi MAC in the frontend.\n\n## Sample output code\n\nThe JSON blob sent by Meraki servers to your app is formatted as follows:\n\n```\n{\n  \"apMac\":\"00:18:0a:79:08:60\",\n  \"apFloors\":[\"500 TF 4th\"],\n  \"observations\":[{\n    \"clientMac\":\"00:11:22:33:44:55:66\",\n    \"probeEpoch\":1388577600,\n    \"probeTime\":\"2014-01-01T12:00:00Z\",\n    \"rssi\":23,\n    \"ssid\":\"SSID 1\",\n    \"manufacturer\":\"Meraki\",\n    \"os\":\"Linux\",\n    \"location\":{\n      \"lat\":37.77057805947924\n      \"lng\":-122.38765965945927,\n      \"unc\":15.13174349529074,\n    },...]\n  }\n}\n```\n\nA specific client device’s details can be retrieved, for example:\n\n`http://pushapi.myserver.com:4567/clients/34:23:ba:a6:75:70` \n\nmay return\n\n```\n{\n  \"id\":65,\n  \"mac\":\"34:23:ba:a6:75:70\",\n  \"seenAt\":\"Fri Apr 18 00:01:41.479 UTC 2014\",\n  \"lat\":37.77059042088197,\"lng\":-122.38703445525945\n}\n```\n\n\n\n## Copyright and license\n\nCode and documentation copyright 2013-2014 Cisco Systems, Inc. Code released under [the MIT license](LICENSE). Documentation released under [Creative Commons](DOCS-LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertcsapo%2Fcisco-meraki-cmx-api-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertcsapo%2Fcisco-meraki-cmx-api-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertcsapo%2Fcisco-meraki-cmx-api-app/lists"}