Skip to content

Commit

Permalink
Docs: Improve Aerospike-related docs (#122)
Browse files Browse the repository at this point in the history
  • Loading branch information
@AntoxaAntoxic
AntoxaAntoxic authored Feb 27, 2024
1 parent b781faf commit bfd7e55
Showing 1 changed file with 72 additions and 37 deletions.
109 changes: 72 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Project configuration is managed through the use of YAML configuration (see reso
### _Requirements_
This section covers the mandatory pre-requisites needed to be able to run the application.

* Windows, Linux, AWS, GCP or MacOS
* Windows, Linux, AWS, GCP or macOS
* JDK 8+
* Maven
* Git
Expand All @@ -19,27 +19,64 @@ This section covers the mandatory pre-requisites needed to be able to run the ap
### _Quick Install_
This section describes how to download, install and run the application.

###### A. Using Maven on MacOS (recommended installation method)
###### A. Using Maven on macOS (recommended installation method)

(1). Clone the repo:

```bash
$ git clone https://github.com/prebid/prebid-cache-java.git
git clone https://github.com/prebid/prebid-cache-java.git
```

(2). Start Redis or Aerospike:
If you have installed [Redis](https://redis.io/docs/install/install-redis/) or [Aerospike](https://aerospike.com/docs/server/operations/install) locally, you may start them both (or separately, depends on your needs) via bash:
```bash
sudo systemctl start redis
sudo systemctl start aerospike
```
Alternatively, you may start DB as Docker image.
You should install [Docker Engine](https://docs.docker.com/engine/install/) if you don't have one.

(2.1) Redis via Docker
1. Pull [Redis docker image](https://hub.docker.com/_/redis) of an appropriate version
```bash
docker pull redis:<version>
```
2. Run Redis container
- the `<version>` should correspond to the pulled image version
- the `<host_port>` should correspond to the `spring.redis.port` property values of the Prebid Cache
```bash
docker run -d --name redis -p <host_port>:<container_port> redis:<version>

# Example (the host will be defined as localhost by default)
docker run -d --name redis -p 6379:6379 redis:7.2.4
```

(2.2) Aerospike via Docker
1. Pull [Aerospike docker image](https://hub.docker.com/_/aerospike) of an appropriate version
```bash
docker pull aerospike:<version>
```
2. Run Aerospike container (the following instruction is enough for the Community Edition only)
- the `<version>` should correspond to the pulled image version
- the `<host_port>` should correspond to the `spring.aerospike.port` property values of the Prebid Cache
- the `<namespace>` should correspond to the spring.aerospike.namespace property value of the Prebid Cache
```bash
$ nohup redis-server &
docker run -d --name aerospike -e "NAMESPACE=<namespace>" -p <host_port>:<container_port> aerospike:<version>

$ sudo service aerospike start
# Example (the host will be defined as localhost by default)
docker run -d --name aerospike -e "NAMESPACE=prebid_cache" -p 3000:3000 aerospike:ce-6.4.0.2_1
```

(2.3) Make sure that the Aerospike and/or Redis is up and running
```bash
docker ps
```

(3). Start the Maven build

```bash
$ cd prebid-cache-java
$ mvn clean package
cd prebid-cache-java
mvn clean package
...
[INFO] Layout: JAR
[INFO] ------------------------------------------------------------------------
Expand All @@ -54,7 +91,7 @@ $ mvn clean package
(4). Run Spring Boot JAR (_from project root_)

```bash
$ java -jar target/prebid-cache.jar
java -jar target/prebid-cache.jar
```

### _Spring Profiles_
Expand All @@ -65,14 +102,14 @@ This section shows examples of the various runtime environment configuration(s).

_VM Options:_
```bash
$ java -jar prebid-cache.jar -Dspring.profiles.active=manage,local -Dlog.dir=/app/prebid-cache-java/log/
java -jar prebid-cache.jar -Dspring.profiles.active=manage,local -Dlog.dir=/app/prebid-cache-java/log/
```

(2). Production with log4j and management endpoints disabled:

_VM Options:_
```bash
$ java -jar prebid-cache.jar -Dspring.profiles.active=prod -Dlog.dir=/app/prebid-cache-java/log/
java -jar prebid-cache.jar -Dspring.profiles.active=prod -Dlog.dir=/app/prebid-cache-java/log/
```

### _Cache Configuration_
Expand Down Expand Up @@ -159,7 +196,6 @@ A configuration object should be passed into the constructor of your custom repo
this.config = config;
}
}

```

Here is an example definition of a custom configuration property class. It is important to replace _'custom'_ with the correct cache implementation name (e.g. redis, memcached, aerospike, etc...). If Spring already provides a predefined configuration property prefix, please use that instead.
Expand All @@ -176,7 +212,6 @@ public class CustomPropertyConfiguration
private String host;
private int port;
}

```

### _Metrics_
Expand Down Expand Up @@ -317,29 +352,29 @@ https://github.com/spring-projects/spring-boot/issues/12188

To launch the JAR from the command line (UNIX/Linux):
```bash
$ ./prebid-cache.jar
./prebid-cache.jar
```

For security reasons, it is recommended to run the service as a non-root user:
```bash
$ sudo useradd prebid-cache
$ sudo passwd prebid-cache
$ sudo chown prebid-cache:prebid-cache prebid-cache.jar
$ sudo chmod 500 prebid-cache.jar
sudo useradd prebid-cache
sudo passwd prebid-cache
sudo chown prebid-cache:prebid-cache prebid-cache.jar
sudo chmod 500 prebid-cache.jar
```

###### B. System V Init

Symbolic link JAR to init.d:
```bash
$ sudo ln -s /app/prebid-cache.jar /etc/init.d/prebid-cache
sudo ln -s /app/prebid-cache.jar /etc/init.d/prebid-cache
```

```bash
$ sudo service prebid-cache start # start service
$ sudo service prebid-cache status # check status
$ sudo service prebid-cache stop # stop service
$ sudo service prebid-cache restart # restart service
sudo service prebid-cache start # start service
sudo service prebid-cache status # check status
sudo service prebid-cache stop # stop service
sudo service prebid-cache restart # restart service
```

Following these steps will allow for:
Expand All @@ -350,7 +385,7 @@ Following these steps will allow for:
###### C. Systemd

/etc/systemd/system/prebid-cache.service:
```bash
```text
[Unit]
Description=Prebid Cache Service
After=syslog.target
Expand All @@ -362,13 +397,12 @@ SuccessExitStatus=143
[Install]
WantedBy=multi-user.target

```
Now you can manage this service with systemctl:
```bash
$ systemctl start prebid-cache.service # start service
$ systemctl stop prebid-cache.service # stop service
$ systemctl status prebid-cache.service # check status
systemctl start prebid-cache.service # start service
systemctl stop prebid-cache.service # stop service
systemctl status prebid-cache.service # check status
```
For more details please refer to man pages for systemctl.

Expand All @@ -379,38 +413,39 @@ This section describes how to run the app in an Elastic Beanstalk environment wi

(1). Go to the project root:
```bash
$ cd prebid-cache-java
cd prebid-cache-java
```

(2). Update codebase :
```bash
$ git pull
git pull
```

(3). Rebuild sources with Maven
```bash
$ mvn clean gplus:execute package
mvn clean gplus:execute package
```

(4). Create folder in work directory:
```bash
$ mkdir aws-prebid-cache
mkdir aws-prebid-cache
```

(5). Copy jar file from prebid-cache-java/target to created directory:
```bash
$ cp prebid-cache-java/target/prebid-cache.jar aws-prebid-cache
cp prebid-cache-java/target/prebid-cache.jar aws-prebid-cache
```

(6). Create Procfile in aws-prebid-cache directory:
```bash
$ sudo nano Procfile
sudo nano Procfile

web: java -jar -Dspring.profiles.active=aws prebid-cache.jar
```

(7). Zip aws-prebid-cache directory
```bash
$ zip -r eb-prebid-cache-new.zip eb-prebid-cache-new
zip -r eb-prebid-cache-new.zip eb-prebid-cache-new
```
Artifact is ready for deploy to Elastic Beanstalk.
For more information, see https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/java-se-platform.html.
Expand Down Expand Up @@ -490,17 +525,17 @@ For using the latest version of prebid cache, perform next steps:

(1). Go to the project root:
```bash
$ cd prebid-cache-java
cd prebid-cache-java
```

(2). Update codebase:
```bash
$ git pull
git pull
```

(3). Rebuild sources with Maven
```bash
$ mvn clean gplus:execute package
mvn clean gplus:execute package
```

If there are any questions, issues, or concerns, please submit them to https://github.com/prebid/prebid-cache-java/issues/.

0 comments on commit bfd7e55

Please sign in to comment.