Documentation
¶
Overview ¶
The Defacto2 application is a self-contained web server first devised in 2023. It is built with the Go language and can be easily compiled for significant server operating systems. The application relies on a PostgreSQL database setup for data queries using a PostgreSQL database connection.
All configurations and modifications to this web application's default settings are through system environment variables.
While you can compile the application to target Windows environments, it is ill-advised as it needs to work correctly with NTFS file paths. Instead, it is advisable to use Windows Subsystem for Linux.
Usage ¶
While it will not be fully functional without directory paths or a database connection, the web server will work out of the box without any configuration provided.
Usage:
defacto2-server
The web server should be available at the unencrypted address, http://localhost:1323.
Commands ¶
There are only two additional commands: one lists the accessible addresses the web server listens on, and the other lists the detected settings.
Usage:
defacto2-server [command]
The commands are:
address List the IP, hostname and port addresses the server is listening on. config List the server configuration options and settings.
Flags ¶
Usage:
defacto2-server [flags]
The flags are:
--help Print the basic command help and exit. --version Print the application version and exit.
Configuration ¶
All application configurations and default modifications are made with environment variables. In systemd, these can be provided using a system service (unit) file, using the Environment assignment under the Service type.
You can use an example of a defacto2.service unit file, which is found in the source code repository in the init/ directory.
A partial example of a defacto2.service unit file:
[Unit] Description=Defacto2 [Service] Environment="D2_MATCH_HOST=localhost" Environment="D2_DATABASE_URL=postgres://root:example@localhost:5432/defacto2_ps" Environment="D2_PROD_MODE=true" "D2_READ_ONLY=false" "D2_NO_CRAWL=true"
Database ¶
This application expects a PostgreSQL database with the Defacto2 "files" table and the connection URL configured in the D2_DATABASE_URL environment variable.
The database connection URL uses a configuration by default but will fail to connect unless the testing Postgres database matches the same values. In production, you must provide a secure and working connection D2_DATABASE_URL variable. The default database connection URL is: postgres://root:example@localhost:5432/defacto2_ps
Some examples:
// local connection D2_DATABASE_URL=postgres://username:password@localhost:5432/database_name // Docker connection D2_DATABASE_URL=postgres://username:password@host.docker.internal:5432/database_name
File assets ¶
The web server uses the following environment variables to offer file downloads, software emulation, web server previews, and thumbnails. All paths must be absolute and valid and must contain tens of thousands of asset files named with universal unique identifiers. The website will turn off the associated feature if the provided path is invalid or contains unexpected files.
D2_DIR_DOWNLOAD is the absolute path to the file downloads directory.
D2_DIR_PREVIEW is the absolute path to the image screenshots directory.
D2_DIR_THUMBNAIL is the absolute path to the squared, image thumbnails directory.
D2_DIR_ORPHANED is the absolute path to the orphaned files directory.
D2_DIR_EXTRA is the absolute path to the extra files directory.
An example download setting:
D2_DIR_DOWNLOAD=/mnt/volume/assets/downloads
Log file storage ¶
When the application runs in production mode, errors or warnings caused by the web server are saved to a log file. The location can be provided using the D2_DIR_LOG variable, which must point to an absolute directory path. Otherwise, the server will create a subdirectory using os.UserConfigDir.
An example log setting:
D2_DIR_LOG=/var/log/defacto2-server
Administrator accounts ¶
The web server uses Google OAuth2 for administrator logins. The server requires a Google OAuth2 client ID to validate admin logins, which is provided in the D2_GOOGLE_CLIENT_ID environment variable.
The server also requires a list of Google OAuth2 user accounts, which is provided in the D2_GOOGLE_ACCOUNTS environment variable. A user account is the JWT "sub" field assertion in the form of a unique integer.
An example accounts setting:
D2_GOOGLE_CLIENT_ID=123-abc.apps.googleusercontent.com D2_GOOGLE_ACCOUNTS=1234567890,0987654321
Production mode ¶
The production mode is on by default and should be enabled in production as it has the following effects.
- It runs file assets and database entry checks on startup.
- Any errors or warnings get appended to a log file.
- If the server crashes, it will recover instead of exiting the program.
- Turns off the Uploader form debug feature.
- Force the administrator logins to be served only over encrypted HTTPS protocols.
To turn off production mode:
D2_PROD_MODE=false
Read-only mode ¶
Read-only mode blocks any website feature that writes to the server database, including the Uploader and administrator database entry edits.
To turn off the read-only mode:
D2_READ_ONLY=true
No crawl mode ¶
The no crawler mode inserts an X-Robots-Tag with the "none" value for all network response headers sent by the web server. The header advises search engines and other bots not to index the website or assets.
To enable no crawl mode:
D2_NO_CRAWL=true
Quiet startup ¶
When quiet is turned on, the majority of startup messages are suppressed. This option is meant for systemd to avoid spamming its log.
To enable quiet mode:
D2_QUIET=true
HTTP and HTTPS ¶
The web server will listen to all HTTP requests on port 1323 without configuration. The value can be changed with the D2_HTTP_PORT variable, which can be set to 0 to disable HTTP.
The D2_TLS_PORT variable, which is turned off by default, allows for an encrypted HTTPS service. In a production situation, you should supply the D2_TLS_CERT and D2_TLS_KEY variables. These should have an absolute path to a TLS (Transport Layer Security) certificate file and key file. If no certificate or key is provided, a dummy certificate will be used, but browsers will reject these.
If the D2_HTTP_PORT and the D2_TLS_PORT values are set to 0, the web server will override to enable port 1323 for HTTP connections. On Linux, ports 1-1023 are considered well-known and reserved for the operating system.
Providing a D2_MATCH_HOST variable can restrict the web server from listening to HTTP and HTTPS requests from a single IP address or host. Otherwise, the web server listens to all requests on the ports.
An example configuration to exclusively use HTTPS and only accept local connections:
D2_HTTP_PORT=0 D2_MATCH_HOST=localhost D2_TLS_PORT=443 D2_TLS_CERT=/etc/ssl/certs/localhost.crt D2_TLS_KEY=/etc/ssl/private/localhost.key
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides the command line interface for the Defacto2 server application.
|
Package cmd provides the command line interface for the Defacto2 server application. |
|
Package handler provides the HTTP handlers for the Defacto2 website.
|
Package handler provides the HTTP handlers for the Defacto2 website. |
|
app
Package app handles the routes and views for the Defacto2 website.
|
Package app handles the routes and views for the Defacto2 website. |
|
download
Package download handles the client file downloads.
|
Package download handles the client file downloads. |
|
html3
Package html3 renders the html3 sub-route of the website.
|
Package html3 renders the html3 sub-route of the website. |
|
htmx
Package htmx handles the routes and views for the AJAX responses using the htmx library.
|
Package htmx handles the routes and views for the AJAX responses using the htmx library. |
|
sess
Package sess provides functions for handling session and cookies.
|
Package sess provides functions for handling session and cookies. |
|
internal
|
|
|
archive
Package archive provides compressed and stored archive file extraction and content listing.
|
Package archive provides compressed and stored archive file extraction and content listing. |
|
archive/internal
Package internal contains the internal functions for the archive package.
|
Package internal contains the internal functions for the archive package. |
|
cache
Package cache provides a lightweight engine for storing key/value pairs.
|
Package cache provides a lightweight engine for storing key/value pairs. |
|
command
Package command provides interfaces for the shell commands and programs on the host.
|
Package command provides interfaces for the shell commands and programs on the host. |
|
config
Package config manages the environment variable configurations.
|
Package config manages the environment variable configurations. |
|
demozoo
Package demozoo handles the retrieval of [production records] from the [Demozoo] API and the extraction of relevant data for the Defacto2 website.
|
Package demozoo handles the retrieval of [production records] from the [Demozoo] API and the extraction of relevant data for the Defacto2 website. |
|
ext
Package ext contains common filename extensions used by the file records.
|
Package ext contains common filename extensions used by the file records. |
|
form
Package form provides functions for providing data for form and input elements.
|
Package form provides functions for providing data for form and input elements. |
|
helper
Package helpers are general, shared functions.
|
Package helpers are general, shared functions. |
|
jsdos
Package jsdos configures the js-dos v6.22 emulator.
|
Package jsdos configures the js-dos v6.22 emulator. |
|
magicnumber
Package magicnumber contains the magic number matchers for identifying file types that are expected to be handled by the Defacto2 server application.
|
Package magicnumber contains the magic number matchers for identifying file types that are expected to be handled by the Defacto2 server application. |
|
magicnumber/pkzip
Package pkzip provides constants and functions for working with PKZip files to determine the compression methods used.
|
Package pkzip provides constants and functions for working with PKZip files to determine the compression methods used. |
|
postgres
Package postgres connects to and interacts with a PostgreSQL database server.
|
Package postgres connects to and interacts with a PostgreSQL database server. |
|
pouet
Package pouet provides production, user voting data sourced from the Pouet website API.
|
Package pouet provides production, user voting data sourced from the Pouet website API. |
|
render
Package render provides the file content rendering for the web server.
|
Package render provides the file content rendering for the web server. |
|
site
Package web proves links and titles for recommended websites.
|
Package web proves links and titles for recommended websites. |
|
sixteen
Package sixteen provides data about releasers and groups on the 16colors website.
|
Package sixteen provides data about releasers and groups on the 16colors website. |
|
tags
Package tags are categories and platform metadata used to classify the served files.
|
Package tags are categories and platform metadata used to classify the served files. |
|
zaplog
Package zaplog uses the zap logging library for application logs.
|
Package zaplog uses the zap logging library for application logs. |
|
Package model provides a database model for the Defacto2 website.
|
Package model provides a database model for the Defacto2 website. |
|
expr
Package expr provides the query mod expressions for the file database.
|
Package expr provides the query mod expressions for the file database. |
|
fix
Package fix contains functions for repairing the database data.
|
Package fix contains functions for repairing the database data. |
|
html3
Package htm3 is a sub-package of the model package that should only be used by the html3 handler.
|
Package htm3 is a sub-package of the model package that should only be used by the html3 handler. |
|
Package runner is used to build and minify the css and js files.
|
Package runner is used to build and minify the css and js files. |