VACbot-lite instructions
1. Installation
1.1. System dependencies
The bot only needs a basic java runtime to function. On Debian and Ubuntu this means the default-jre-headless package.
(For Debian 10 and 11, this installs openjdk-11-jre-headless. For Debian 12, this installs openjdk-17-jre-headless.)
All other required libraries (JARs) are included in the archive.
The screen package is needed to run the bot in the background.
The sqlite3 package is not needed but nice to have for database management.
1.2. Bot account and directory
The bot can run under any account and can be located in any directory.
Personally, I prefer to create a separate account vacbot and its new home directory /home/vacbot.
This is how it will be used in later sections of these instructions.
1.3. Archive content
Extract the bot archive to the chosen directory (output shortened and modified to show important items):
vacbot@vps:~$ tar xzvf VACbot-lite-0.1.tar.gz
VACbot-lite-0.1/vacbot/... [bot code in Java .class files]
VACbot-lite-0.1/lib/... [necessary Java libraries in JAR files]
VACbot-lite-0.1/VACbot.properties [the only configuration file]
VACbot-lite-0.1/SQL/vacbot_empty.db [pre-made empty database]
VACbot-lite-0.1/SQL/vacbot_kunos_and_carpacks.db [pre-made database with default skins added]
VACbot-lite-0.1/run.sh [shell script to start the bot]
VACbot-lite-0.1/systemd/vacbot.service [systemd file to support automatic start]
1.4. Database
With the lite version of the bot I moved from PostgreSQL to SQLite. The latter stores everything in a single file in the bot's directory.
The database contains only two tables:
car_default_skins - This table should contain list of all default skins. Basically it is a list of skins that the bot does not accept on upload, so that the user cannot overwrite the default skin.
car_custom_skins - Informations about uploaded custom skins are stored here.
You can build the database yourself or use one of the pre-made ones.
Using pre-made database
Simply copy the chosen database file to the robot's home directory as the vacbot.db file (like /home/vacbot/vacbot.db).
vacbot_empty.db - Empty database.
vacbot_kunos_and_carpacks.db - Database pre-filed with all Kunos skins and also many other imported for VAC and THR (nearly 3000 skins in total).
Building database yourself
The empty database file is ready to use, but you can make it yourself in the SQL directory if needed:
vacbot@vps:~/VACbot-lite-0.1/SQL$ sqlite3 -init db_create_vacbot-lite.sql vacbot.db ""
-- Loading resources from db_create_vacbot-lite.sql
You can fill the empty database with default skins from CSV files (some CSV files are available in the SQL directory, but you can make your own):
vacbot@vps:~/VACbot-lite-0.1/SQL$ sqlite3 vacbot.db
SQLite version 3.34.1 2021-01-20 14:10:07
Enter ".help" for usage hints.
sqlite> .mode csv
sqlite> .import car_skins_kunos.csv car_default_skins
sqlite> .import car_skins_carpacks.csv car_default_skins
sqlite> .quit
1.5. Configuration
All the bot configuration is in the file VACbot.properties which contains the following options:
BOT_TOKEN=blahblahblah
You have to set it to the long string provided by Discord.
DISCORD_MANAGEMENT_CHANNEL_ID=642371142841270303
ID of your Discord management channel (big decimal number).
DISCORD_SKIN_UPLOAD_CHANNEL_ID=619892513591001090
ID of your Discord skin upload channel (big decimal number).
SQLITE_DB_FILE=/home/vacbot/vacbot.db
Path to the bot's database file.
TEMP_UPLOAD_DIR=/home/vacbot/temp
All uploaded files and unpacked preview images are stored in this directory during processing. Rejected files will not be deleted. Files here can be safely deleted at any time.
CUSTOM_SKINS_DIR=/home/vacbot/skins
All processed archives with skins and preview images are stored here. It is also skin download directory (point your webserver here). Do not touch the content, as it is closely tied to the database content. Manipulation is only possible by a bot command.
BASE_URL=https://vac.vacbot.cz/skins/
Address used for the construction of download links.
REQUIRED_SKIN_PREFIX=vac_
Limit uploaded skins so that their names start with the chosen prefix. Comment out with # if you don't need it.
Make sure that the configured directories exist and are writable by the bot. The same applies to the database file.
2. Start
2.1. Manual start
Especially for testing purposes. Logged messages are clearly visible and an invite link is also available.
vacbot@vps:~/VACbot-lite-0.1$ ./run.sh
[main] INFO vacbot.VACbot - Reading config...
[main] INFO vacbot.VACbot - Checking SQL...
[main] INFO vacbot.VACbot - Connecting to Discord...
[main] INFO vacbot.VACbot - You can invite me by using the following url: https://discord.com/oauth2/authorize?client_id=...
[main] INFO vacbot.VACbot - Checking management channel...
[main] INFO vacbot.VACbot - Checking skin upload channel...
[main] INFO vacbot.VACbot - Adding channel listeners...
[main] INFO vacbot.VACbot - Bot is now running...
(CTRL+C to stop the bot.)
2.2. Start as a service
This depends on the init system used. For systemd, just copy the vacbot.service file to the /etc/systemd/system/ directory.
Then you can start the bot by: systemctl start vacbot
And enable auto-start by: systemctl enable vacbot
Important note: There is hardcoded path to the bot's directory in the vacbot.service file. You need to change it appropriately according to your installation.
Instead of changing this file every time the version changes, I recommend making a symlink to the current version in the bot's home directory, like:
vacbot@vps:~$ ln -sf VACbot-lite-0.1 VACbot-lite
vacbot@vps:~$ ls -l VACbot-lite
lrwxrwxrwx 1 vacbot vacbot 15 Dec 31 14:05 VACbot-lite -> VACbot-lite-0.1
3. Operation
3.1. Skin upload channel commands
skin upload
There is no command for this, the robot simply tries to process any message with exactly one file attached.
It is now also possible to include driver files in the skin archive.
Requirements for the file to be accepted:
- Archive format is .7z or .zip.
- The files belonging to the skin have a path:
content/cars/<car_name>/skins/<skin_name>/<file>
- No unusual characters in the <car_name> and <skin_name>.
- The combination od <car_name> and <skin_name> is not some of the default skins.
- The combination od <car_name> and <skin_name> is not a skin already uploaded by someone else.
- If configured, the <skin_name> starts with defined prefix.
- Exactly one skin in the archive (this also means that it is not possible to have driver files without a skin).
- The files belonging to the driver itself have a path:
content/driver/<driver_name>/<file>.kn5
- No unusual characters in the <driver_name>.
- The files belonging to the driver textures have one of the folowing paths:
content/textures/driver_helmet/<...>/<file>.dds
content/textures/driver_gloves/<...>/<file>.dds
content/textures/driver_suit/<...>/<file>.dds
- No driver textures without driver itself.
!myskins
!myskins
Displays a list of skins in the database belonging to the user.
3.2. Management channel commands
!list
!list database
Lists content of the car_custom_skins table to a CSV file.
!list files
Lists content of the CUSTOM_SKINS_DIR directory to a CSV file.
!list temp
Lists content of the TEMP_UPLOAD_DIR directory to a CSV file (to quickly check rejected archives).
!links
!links
Generates download links from the database (not from the CUSTOM_SKINS_DIR content!) to a TXT file.
!cmlink
!cmlink
Generates Content Manager one-click skin installation link to a TXT file.
!cleanup
!cleanup temp
Deletes the files in the TEMP_UPLOAD_DIR directory.
!cleanup channel
Deletes messages in the skin upload channel.
!cleanup all
Deletes everything, i.e. car_custom_skins database table content, files in TEMP_UPLOAD_DIR, files in CUSTOM_SKINS_DIR and messages in the skin upload channel.
4. Known imperfections
- VACbot.properties file is in the VACbot directory, so don't forget to replace it with the correct one when updating the bot.
- With the lite version of the bot I changed the logging framework and added many logging messages. Unfortunately I haven't had time to check if the bot logs properly when running in the background.
- If someone updates their skin and changes the archive format (.zip -> .7z or .7z -> .zip), the original archive is not deleted from the CUSTOM_SKINS_DIR directory. However, it is not present in the database nor in the download links, which means it is safe to delete it.
- It is not known to me what files may belong to the driver. When including driver files, it is possible that an obviously valid archive will be rejected or, on the contrary, an obviously defective archive will be accepted.
---- END ----