Browse files

freegeoip v3.0

New version of the freegeoip web server.


- Configuration file is gone. All switches are in the command line now.

- The updatedb script is gone. Now the server does some background job
  to download and maintain the database file up to date.

- Auto-reload of the database. If you update or overwrite the database
  file the server reloads it automatically with no service interruption.

- Single file front-end. No longer serving any JS or CSS, using it all
  from the cloud. jQuery is gone and the front-end is based on AngularJS
  and Bootstrap only.

- No more DNS contention. If you're running your own server and need
  that then use something external, like dnsmasq.

- Database date is exposed to clients in the X-Database-Date header.

- Preliminary IPv6 support. Closes #21.

- Localized country, region and city names. The server uses the
  Accept-Language header to determine the language of the response.

- Official docker support. See the Dockerfile for details.

- New package freegeoip for Go. All the above and more tidbits in a Go
  package that other programs can leverage.

This version of the freegeoip web server is backwards compatible with
the previous version. The HTTP API is virtually the same.

Features of the freegeoip Go package:

- Database API that allows any Go program to do IP geolocation lookups.
  It supports both local and remote databases.

- Background goroutine to download and maintain the database up to date.

- Background goroutine for monitoring the database file and
  auto-reloading on demand. Uses fsnotify.

- An http.Handler object that any net/http server can use to serve IP
  geolocation lookups. Supports CSV, XML, JSON and JSONP out of the box.

- Extensible encoder interface to support other output formats, or to
  implement custom responses for the http handler.

- Decent test coverage.
  • Loading branch information...
1 parent cb37fe2 commit 0e7907bd8b80a4759e2291f50f20b3e6e726cb4c @fiorix committed Nov 14, 2014
@@ -1,7 +1,7 @@
@@ -0,0 +1,10 @@
+language: go
+ - 1.3
+ - release
+ - tip
+ - go test -v -cover
+ - go get
@@ -0,0 +1,11 @@
+# This is the official list of freegeoip authors for copyright purposes.
+# This file is distinct from the CONTRIBUTORS file.
+# Names should be added to this file as
+# Name or Organization <email address>
+# The email address is not required for organizations.
+# Please keep the list sorted.
+Alexandre Fiori <>
@@ -0,0 +1,21 @@
+# This is the official list of freegeoip contributors for copyright purposes.
+# This file is distinct from the AUTHORS file.
+# Names should be added to this file as
+# Name or Organization <email address>
+# Please keep the list sorted.
+# Use the following command to generate the list:
+# git shortlog -se | awk '{print $2 " " $3 " " $4}'
+# The email address is not required for organizations.
+Alex Goretoy <>
+Gleicon Moraes <>
+Leandro Pereira <>
+Lucas Fontes <>
+Matthias Nehlsen <>
+Melchi <>
+Vladimir Agafonkin <>
@@ -1,20 +1,10 @@
FROM google/golang
-RUN apt-get install -y build-essential libsqlite3-dev pkg-config file supervisord
-WORKDIR /gopath/src/app
-ADD . /gopath/src/app/
-RUN go get app
-RUN cd /gopath/src/app/
-RUN go build
-#... will download files and process them to create ipdb.sqlite
-RUN cd db && ./updatedb
-RUN file /gopath/src/app/db/ipdb.sqlite
-RUN /usr/bin/install -o www-data -g www-data -m 0755 -d /var/log/freegeoip
-EXPOSE 8080
-CMD []
-ENTRYPOINT ["/gopath/bin/app"]
+ADD . /gopath/src/
+WORKDIR /gopath/src/
+RUN go get
+RUN go install
+RUN cp -r public /var/www
+ENTRYPOINT ["/gopath/bin/freegeoip"]
+CMD ["-public", "/var/www"]
@@ -0,0 +1,55 @@
+# History of
+The freegeoip software is the result of a web server research project that
+started in 2009, written in Python and hosted on
+[Google App Engine]( It was rapidly adopted by
+many developers around the world due to its simplistic and straightforward
+HTTP API, causing the free account on GAE to exceed its quota every day
+after few hours of operation.
+A year later freegeoip 1.0 was released, and the domain
+moved over to its own server infrastructure. The software was rewritten
+using the [Cyclone]( web framework, backed by
+[Twisted]( and [PyPy]( in
+production. That's when the first database management tool was created,
+a script that would download many pieces of information from the Internet
+to create the IP database, an sqlite flat file used by the server.
+This version of the Python server shipped with a much better front-end as
+well, but still as a server-side rendered template inherited from the GAE
+version. It was only circa 2011 that freegeoip got its first standalone
+front-end based on jQuery, and is when Twitter bootstrap was first used.
+Python played an important role in the early life of freegeoip and
+allowed the service to grow and evolve fast. It provided a lot of
+flexibility in building and maintaining the IP database using multiple
+sources of data. This version of the server lasted until 2013, when
+it was once again rewritten from scratch, this time in Go. The database
+tool, however, remained intact.
+In 2013 the Go version was released as freegeoip 2.0 and this version
+had many iterations. The first versions of the server written in Go were
+very rustic, practically a verbatim transcription of the Python server.
+Took a while until it started looking more like common Go code, and to
+have tests.
+Another important change that shipped with v2 was a front-end based on
+AngularJS, but still mixed with some jQuery. The Google map in the front
+page was made optional to put more focus on the HTTP API. The popularity
+of freegeoip has increased considerably over the years of 2013 and 2014,
+calling for more.
+Enter freegeoip 3.0, an evolution of the Go server. The foundation of
+freegeoip, which is the IP database and HTTP API, now lives in a Go
+package that other developers can leverage. The freegeoip web server is
+built on this package making its code cleaner, the server faster,
+and requires zero maintenance for the IP database. The server downloads
+the file from MaxMind and keep it up to date in background.
+This and other changes make it very Docker friendly.
+The front-end has been trimmed down to a single index.html file that loads
+CSS and JS from CDNs on the internet. The JS part is based on AngularJS
+and handles the search request and response of the public site. The
+optional map has become a link to Google Maps following the lat/long
+of the query results.
@@ -1,4 +1,4 @@
-Copyright (c) 2013 Alexandre Fiori. All rights reserved.
+Copyright (c) 2009-2013 The freegeoip authors. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
Oops, something went wrong.

0 comments on commit 0e7907b

Please sign in to comment.