Installing exchanger-api / DONE

Rest-API installation on your own servers is available only if you purchase a full BoxExchanger software licence

Docker

Prepare dependencies

apt update
apt upgrade -y
apt install -y nano sudo curl wget

1. Install Docker and Docker Compose

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

2. Create runner user and add it to sudoers

sudo adduser --disabled-password --gecos "" runner
sudo usermod -aG sudo runner

3. Create docker group and add user to it

sudo usermod -aG docker runner

4. Switch to a 'runner' user

sudo su runner

newgrp docker

5. Create docker network

docker network create --subnet 10.1.0.0/24 exchanger-net

6. Docker login

• Create a Personal Access Token in GitLab

• Make sure to tick the read_registry permission scope

• Create a reminder to update the PAT after expiration date, as once it expires you lose access for updates. https://git.boxexchanger.net/-/profile/personal_access_tokens

• Login to docker read_registry

  docker login rg.boxexchanger.net
  
  # Username: your_gitlab_username
  # Password: your_gitlab_pat

7. Create required folders

mkdir -p /home/runner/api_server
mkdir -p /home/runner/api_server/config
mkdir -p /home/runner/api_server/public
cd /home/runner/api_server

8. Create your configurations (.env)

nano /home/runner/api_server/.env

Below example configuration .env Insert your variables PROJECT_NAME and API_URL

PROJECT_NAME="Project_name"
API_URL="https://www.domain.name/service/"
REDIS_URI="redis://exchanger-api-redis:6379/0"
UPLOADER_URL="http://exchanger-uploader-service:3013/"

9. Create nginx configuration for api

Create /home/runner/api_server/nginx_api.conf file with following contents

nano /home/runner/api_server/nginx_api.conf

Example nginx config.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ""      close;
}

server {
    listen 3000;
    server_name default;

    location /service/ {
        proxy_pass http://exchanger-api:3010/;
        proxy_http_version 1.1;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_redirect off;
    }
    location /service/fs {
        alias /public;
    }
    location /ws/ {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_pass http://exchanger-api:3011/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_redirect    off;
    }

    access_log off;
    error_log  /var/log/nginx-error.log error;
    sendfile off;
    client_max_body_size 100m;
}

10. Create your docker-compose.yml

nano /home/runner/api_server/docker-compose.yml

Below example of docker compose file where you must change $VCS_NAMESPACE to your git group path for example bx4/project-name

x-logging:
      &default-logging
      driver: "json-file"
      options:
        max-file: "1"
        max-size: "500m"

services:
  exchanger-api:
    image: rg.boxexchanger.net/$VCS_NAMESPACE/exchanger-api:master
    container_name: exchanger-api
    restart: unless-stopped
    read_only: true
    env_file:
      - .env.mongo.user
      - .env
    volumes:
      - ./config:/app/config
      - ./public:/app/public
      - ./pluginsExternal:/app/pluginsExternal
      - type: tmpfs
        target: /home/node/.pm2/
        tmpfs:
          size: "10000000"
    logging: *default-logging
    networks:
      exchanger-net:
        ipv4_address: 10.1.0.101

  exchanger-uploader-service:
      image: rg.boxexchanger.net/boxexchanger-utils/exchanger-uploader-service:master
      container_name: exchanger-uploader-service
      restart: unless-stopped
      read_only: true
      volumes:
        - ./public:/public
      logging: *default-logging
      networks:
        exchanger-net:
          ipv4_address: 10.1.0.104
  exchanger-email-service:
      image: rg.boxexchanger.net/boxexchanger-utils/exchanger-email-service:master
      container_name: exchanger-email-service
      restart: unless-stopped
      read_only: true
      volumes:
        - ./config:/app/config:ro
      logging: *default-logging
      networks:
        exchanger-net:
          ipv4_address: 10.1.0.106

  exchanger-api-mongodb:
    image: mongo:6
    container_name: exchanger-api-mongodb
    restart: unless-stopped
    networks:
      exchanger-net:
        ipv4_address: 10.1.0.102
    volumes:
      - mongo_db:/data/db
      - /backups:/backups
      - ./init_db.js:/docker-entrypoint-initdb.d/init.js
    logging: *default-logging
    ports:
      - 127.0.0.1:27017:27017
    env_file:
      - .env.mongo.root

  redis:
    image: redis:7
    container_name: exchanger-api-redis
    restart: unless-stopped
    read_only: true
    volumes:
      - redis_data:/data
    logging: *default-logging
    networks:
      exchanger-net:
        ipv4_address: 10.1.0.103

  nginx-api:
    image: nginxinc/nginx-unprivileged:1.25-alpine
    container_name: nginx-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    networks:
      exchanger-net:
        ipv4_address: 10.1.0.100
    logging: *default-logging
    volumes:
      - ./nginx_api.conf:/etc/nginx/conf.d/default.conf:ro
      - ./public:/public:ro
      - type: tmpfs
        target: /docker-entrypoint.d/
        tmpfs:
          size: "100000"
      - type: tmpfs
        target: /tmp/
        tmpfs:
          size: "10000000"

volumes:
  mongo_db:
  redis_data:

networks:
    exchanger-net:
        external: true

11. Execute credential mongo generation script

cd /home/runner/api_server
wget "https://git.boxexchanger.net/-/snippets/2/raw/main/init_db.js"
wget "https://git.boxexchanger.net/-/snippets/2/raw/main/generate_credentials.sh"
chmod +x generate_credentials.sh
./generate_credentials.sh

12. Initialize MongoDB

docker compose up -d exchanger-api-mongodb

13. Start API server

docker compose up -d

14. Get and remove initial admin credentials:

docker exec exchanger-api cat access.txt

• remove access.txt

  docker exec exchanger-api rm access.txt

Sources