Quickstart#

Prerequisites#

Ensure that you have installed mkcert (and the corresponding NSS tools). You can run mkcert -install to verify your installation. coreutils adds GNU utils to macOS. timeout from the package is required.

Note: Our Docker compose configuration requires specific environment configuration that is automatically handled by just. While you can run compose directly, it’s advised to use the just dc alias for docker-compose as this ensures the environment will be properly configured.

Steps#

Ensure that the Docker daemon is running.

Clone the repository and cd into it. This is the monorepo root.

git clone https://github.com/WordPress/openverse-api.git
cd openverse-api/

Generate locally-trusted certificates. These will be used by the NGINX proxy to serve the API over https.
```
just cert
```
From the monorepo root, bring up the Docker Compose system. Docker Compose will automatically read the necessary environment variables from env.docker files from project directories.
```
just up
```
Point your browser to http://localhost:50280. You should be able to see the API documentation.
Load the sample data. This could take a couple of minutes.
```
just init
```

Make an API request using cURL. You should receive a JSON response.

just stats

Piping the response through a pretty-printer like jq should yield an output like the following.

just stats | jq '.[0]'

{
  "source_name": "flickr",
  "display_name": "Flickr",
  "source_url": "https://www.flickr.com",
  "logo_url": null,
  "media_count": 1000
}

When done, bring the system down. To remove all volumes as well, pass the -v flag.
```
just down
just down -v # removes volumes
```
Use the logs command access the logs from all services. To isolate a service, pass the service name as an argument.
```
just logs
just logs web # only shows logs web service
```

Services#

The command just up spawns the following services:

PostgreSQL x 2 instances
- upstream data source simulator
- API application database
Elasticsearch
Redis
NGINX
web (api/)
ingestion_server and indexer_worker (ingestion_server/)

The last two are subprojects of this monorepo.

Troubleshooting#

If the Elasticsearch container fails to start on your machine, there’s a good chance the container ran out of memory. Ensure that you have allocated enough memory to Docker applications and re-run the just up command.

If the logs mention “insufficient max map count”, you may also need to increase the number of open files allowed on your system. For most Linux machines, you can fix this by adding the following line to /etc/sysctl.conf:

vm.max_map_count=262144

To make this setting take effect, update kernel state:

sudo sysctl -p