PostgreSQL
This guide will help you set up a dockerized Objectiv Collector with a PostgreSQL data store. It can be used locally for development, or in production.
If you want to test-drive Objectiv without having to set up a backend & data store, try Objectiv Go to quickly spin up a fully functional Objectiv pipeline locally.
The Tracker SDKs can also be configured to use Transports that do not rely on the Collector, such as DebugTransport.
1. Starting the Collector docker containers
Assuming you have Docker and Git installed, run the following commands:
# create a checkout of the git repo
git clone https://github.com/objectiv/objectiv-analytics.git
# enter the repo and spin up the docker containers
cd objectiv-analytics
docker-compose -f docker-compose-dev.yaml pull
docker-compose -f docker-compose-dev.yaml up -d
# Verify the status:
docker-compose -f docker-compose-dev.yaml ps
This will spin up two images:
objectiv_collector
: An endpoint that the Objectiv-tracker can send events to (http://localhost:8081).objectiv_postgres
: The database.
The above docker-compose command starts a Postgres container that allows connections without verifying passwords. Do not use this in production or on a shared system!
2. Querying the database directly
To connect to the running DB, simply execute:
docker exec -ti objectiv_postgres psql -U objectiv
or by using a local client:
psql -U objectiv -h 127.0.0.1
3. Stopping and cleanup
To stop the running containers run:
# stop containers
docker-compose -f docker-compose-dev.yaml down
# clean up PG volume
docker volume rm objectiv-analytics_pgdata
Removing the docker volume will also remove any data in the database.
FAQ
Where are Postgres' permissions configured?
As this is a demo environment, permissions are pretty simple; the credentials are set defined at the top of the
docker-compose-dev.yaml
file, and imported by the containers that need them.
Can I access the Collector over a network connection?
The opened ports are only exposed on localhost (127.0.0.1
). So to access over the network, or ipv6, additional
configuration may be necessary.
Troubleshooting
I get a FetchTransport error in the browser console
If you see this error for tracking calls, the Collector probably didn't start correctly, or cannot listen on the specified port.
- Go to
http://localhost:[PORT]/schema
(e.g. http://localhost:8081/schema) and verify you see the schema. - If you don't, go to
http://localhost:[PORT]/
(e.g. http://localhost:8081/) and verify you see a aMethod not allowed
message or a500
error message. - If not, let's check the Collector logs for clues, and resolve any issues you see in there.
docker logs objectiv_collector
- If the logs don't yield any clues, it's possible that the Collector cannot listen on the given port (by
default port
8081
). Let's see if this is the case below.
- Linux
- MacOS
- Windows
sudo lsof -n -i :[PORT_NUMBER]
netstat -an |grep [PORT_NUMBER]
netstat -aon | findstr :[PORT_NUMBER]
On Linux the Collector will simply refuse to start if it cannot bind to the port. On Windows/Mac this is different, because the container is running in a VM. Getting the Collector to run on MacOS can also vary a bit depending on the OS version.
Once you identify the application running on the same port, stop it, and restart the Collector.
The Postgres container is not starting properly
The Postgres container tries to bind to port 5432 to enable local access. This won't work if something else is already using that port. To solve this, stop the application that's running on port 5432 (see previous section) and restart the Collector.
My database changed and it no longer works
At the first start-up, Postgres will be initialised. This means a database will be created. As this is persisted on disk (in a docker volume), on subsequent startups, the persisted database will be loaded. In case of database changes, this may cause problems (as they are also persisted).
To reset the database, simply do the following:
# stop the containers
docker-compose -f docker-compose-dev.yaml down
# remove the volume
docker volume rm objectiv-analytics_pgdata
# restart the containers
docker-compose -f docker-compose-dev.yaml up -d
The name of the docker volume that you remove in the example above, is determined by the directory from which
the instance was started. So if your checkout dir is in fact objectiv-analytics, this is correct, otherwise
you probably need to find the name of the volume first (docker volume ls
), and remove that.
My issue is not listed here
Please get in touch with us via the options in the box below.