Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve Aerospike-related docs #122

Merged
merged 5 commits into from
Feb 27, 2024
Merged

Improve Aerospike-related docs #122

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3966ec4
Improve Aerospike-related docs
AntoxaAntoxic Nov 29, 2023
cde1170
Refactored Aerospike via Docker doc, added similar doc for Redis
VeryExtraordinaryUsername Jan 16, 2024
ad7d4f3
Post-review updates #1
VeryExtraordinaryUsername Jan 16, 2024
6ef8cd9
Post-review updates #2
VeryExtraordinaryUsername Jan 18, 2024
c8ef440
Fix markdown inconsistencies
Net-burst Feb 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 72 additions & 37 deletions README.md
View file
Open in desktop
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>
VeryExtraordinaryUsername marked this conversation as resolved.
Show resolved Hide resolved
```
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/.
Loading