README.md

Spring GeekApk Server

_{(illustration by duangsuse)}

The way to get started is to quit talking and begin doing. — Walt Disney

Introduction

GeekApk Spring server built with (*v*) and Kotlin/SpringBoot by ♥\_(ㇱ)_/✐

Features in version 1.0♭

• Migrations (Export data tables to binary file)
• RPC interfaces (server, admin, category, user, app/collab, reversion, comment, star, follow, timeline, notification)
• User last online, App pinned comment
• GeekApk bot i18n
• Minimal counter check before Data pull
• MetaApp for users
• AppType, GeekApk bot
• Query Combating Language support (bulk query)
• Lexical scoping (lambda calculus) for the QCL Interpreter
• GeekPush Server-side-push support

Deploying

Java Runtime

GeekApk Spring is a simple application, or microservice (and transitively, JavaEE Platform Application) built against SpringBoot

A Java Runtime with sufficient dynamic linking requirements (like spring boot runtime dependencies) is required to run GeekApk

This project's Kotlin compiler is configured to generate code for JVM 1.8, which is popular in nowadays Java server-side development

Requirements: JRE 1.8 or above

Recommended: Oracle JDK/JRE or OpenJDK 8-11

GraalVM with Ahead-Of-Time optimizations is also a good option for the server program runtime (since SpringBoot has been migrated to SubstrateVM)

Required configuration properties

Since GeekApk is a RDBMS-based web backend application, a working PostgreSQL DBMS instance is required to run GeekApk

Setup the GeekApk database with following commands

psql -c 'CREATE DATABASE geekapk_db;' -U postgres # Create database in pg clusters for geekapk with user postgres
sudo -u postgres psql

(and execute SQL statements)

CREATE USER geekapk WITH PASSWORD 'password'; -- Create geekapk application database user

GRANT ALL PRIVILEGES ON DATABASE geekapk_db TO geekapk; -- Make this database geekapk owned

To make a usable database for GeekApk

For database connection and authentication, you may need to change the cluster's pg_hba.conf, please make sure that PostgreSQL is only accepting connections from local loopback for server security.

All microservice properties are in ./application.properties nested in application classpath

Make GeekApk a service (continuous running)

We suppose that you choose to deploy geekapk service to your own Linux machine, in most cases this means you will deploy your service onto your VPS

Amazon Lambda / OpenShift and others is not talked here.

Systemd is a popular daemon service manager in modern GNU/Linux distributions, and it's recommended to use when making microservices continuous running

create a file with these content in /lib/systemd/system/geekapk_spring.service:

[Unit]
Description=GeekApk Spring server
After=network.target
Requires=postgresql.service

[Service]
Type=simple

# Recommended to run as 
User=geekapk
Group=geekapk
WorkingDirectory=/home/geekapk/service

LimitNOFILE=10
ExecStart=#Your server start command

Restart=always
RestartSec=2

Environment=Key=Value K=V

CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE

#ExecStartPre=-/bin/setcap 'cap_net_bind_service=+eip' your_server_jvm_binary
#PermissionsStartOnly=true # Only ExecStartPre to be run as root (but not ExecStart)

[Install]
WantedBy=multi-user.target

(see systemd service file format manual by man systemd.service, you can edit config file using nano, vi and vim)

Then you can use sudo systemctl start geekapk_spring to start the server

For server status checking, execute shell command sudo systemctl status geekapk_spring.service

And when you're sure about your configuration, run sudo systemctl enable geekapk_spring to auto-start the service when system boots

Process control daemon Supervisor is also a good option for this case

man page for systemd | related practice | related document

(Optional) Make a reverse proxy

CloudFlare is also a usable option for reverse proxying the service

Nginx configuration

user www-data;
worker_processes 4;
pid /run/nginx.pid;

events {
    worker_connections 65535;
    multi_accept on;
}

http {
    include mime.types;
    upstream geeksvc {
        server localhost:233;
    }

    server {
        listen 80;
        server_name api.geekapk.org;

        location / {
            proxy_pass http://geeksvc;
            proxy_redirect off;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }
}

Apache configuration

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

<VirtualHost *:443>
    ServerName api.geekapk.org
    ProxyPass / http://localhost:233/
    ProxyPassReverse / http://localhost:233/
</VirtualHost>

Server stress testing

You can use wrk / siege / ab for server stress testing

You SHOULD NOT stress testing on the production environment GeekApk API service, run stress tests on private machines.

# Using Apache HTTP server benchmarking tool
ab -n request_num -t timeout -c concurrency -m http_method -C cookie http://127.0.0.1:8080/

# Using Siege, a HTTP/FTP load tester and benchmarking utility
# -b means "no delays between requests"
siege -b -n request_num -t timeout -c concurrency -H "Cookie: ${cookies}" http://127.0.0.1:8080/

# use man ab / siege for documents

# Wrk is not packaged for most distributions, through.
# You can install it from scratch with the documentation from https://github.com/wg/wrk/wiki/Installing-Wrk-on-Linux

Configuration

All GeekApk application related properties (e.g. server access password) is in info.ini (default settings) and can be overridden in geekapk.ini, message translations (string templates) can be found in translations.ini

Add your configuration override file paths separated by column : in environment variable GEEKAPK_INI

Those configuration files are self-documented, just read inline comments and set the values on your purpose

API Mapping

Main

• / API Index, help message
• /serverVersion Server version string
• /serverDescription description string
• /serverBoot bootUp datetime
• /detail server detail map

Others

The GeekApk API Server has built-in API documents, see API Index

References

• GeekApkR GitHub Organization

• GeekApk GitHub Organization

• GeekApkSpecShort GitHub Gist

Future reading

• GeekApk 参与者公约
• Pull Request 需知
• 贡献指南 Contributing guides
• APIs for GeekApk v1.0b
• Rebase server
• Testable Solutions for Modern Applications Book
• Old Python Bottle
• Old Rust
• Times news API server
• GeekApkR Gaee

License

Copyright (C) 2019  duangsuse

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.