This package is an API Gateway written in Rust, supported by a browser-based UI written in React
- The Rust build toolchain and package manager (Cargo)
- Follow instructions at rustup.rs to install this tooling
- This project was last built using Rustc/Cargo version 1.77.2 (stable), but I don't believe it uses anything particularly fringe in the language, so earlier builds should work as well.
- NodeJS
- Built using version 18
- SurrealDB
- OpenSSL (likely already installed)
This project includes a Submodule for the Web UI components. This delineation separates the languages between the repositories because the UI leverages React/JS for its presentation. Initializing the submodule can be done as follows
git submodule update --init --recursive --remove && git submodule foreach git checkout main
This step requires the git submodule to be initialized.
This step requires that NodeJS be installed (last built with version 18)
See the readme within the UI project for detailed instructions. For a high-level build, follow these steps:
cd webui
npm install
npm run build-dist
This generate a collection of static files located in the www
directory
that will be served by the gateway to service the User Interface.
Running the included generate-certs.sh script will require that
openssl
is installed on your machine, and accessible to the current user.
Running this project requires that an X.509 Certificate be available for use to leverage TLS for HTTPS communications. At a future time, this location may be made configurable, but for now, they need to positioned relative to the present working directory like so:
- PEM-formatted RSA Private Key at
.ssl.dev/snakeoil.key
- X.509-formatted Certificate, at
.ssl.dev/snakeoil.pem
For convenience a script has been written to automate the generation of self-signed certificates in the correct place, relative to the root of this project directory.
This step will require that the Rust package manager, Cargo, and the Rust toolchain are installed.
To build the project, simply run cargo build
for an unoptimized dev version,
or cargo build --release
for an optimized release build of the application.
The gateway has been verified to build correctly on MacOS and Linux, for the x84_64 architecture.
To run the gateway on a MacOS machine, you'll need to add a loopback Alias for the IP Address 127.0.2.1 like this:
sudo ifconfig lo0 alias 127.0.2.1
Because the gateway binds to port 443, which is protected, the gateway will normally be required to run as the root user. Using a utility like authbind can alleviate some of this by granularly allowing access on specific ports for specific users.
For the User interface to correctly operate, you'll need to add the following entry to your hosts file:
127.0.2.1 apigateway.local
To start the gateway service (after building), run the following command:
sudo target/release/api-directory
Alternatively, the debug build can be more directly built and run using cargo:
sudo cargo run
See the section above about
authbind
for Linux runtime if you'd like to avoid usingsudo
to run the program bound to port 443.
This step will require leveraging the SurrealDB directly. Normal operation does not require the separate SurrealDB application, but the inital User setup does. SurrealDB should be downloaded and installed for these next steps. Follow the SurrealDB Installation steps for your system of choice to continue.
After running the Gateway for the first time, the Database will be created in
the temp.speedb
directory. Then, run the SurrealDB server on the
database files.
surreal start file:temp.speedb
In a separate terminal, open a SQL Shell client, and insert the Admin role and User.
surreal sql --ns api_directory --db services
api_directory/services> INSERT INTO role { namespace: "Gateway", name: "Admin" }
api_directory/services> INSERT INTO gateway_user { username: "admin" }
At this point, there will be a Role Id and a User ID shown in the SQL Shell, like this:
- for role:
role:wadr6xbtms53q660ho9v
- for user:
gateway_user:uiqnmjhfp7fl3cs9d18a
The last step will be to relate the user as a member of the role.
api_directory/services> RELATE gateway_user:uiqnmjhfp7fl3cs9d18a->memberOf->role:wadr6xbtms53q660ho9v
To check that the records have been correctly inserted, you can query the database for the related records, and it should return the records:
api_directory/services> select username, ->memberOf->role.namespace, ->memberOf->role.name FROM gateway_user
[[{ "->memberOf": { "->role": { name: ['Admin'], namespace: ['Gateway'] } }, username: 'admin' }]]
Then, close both the Surreal SQL shell and shut down the SurrealDB server.
- Go to the web portal and select "Reset it here" from the login page.
- Enter the desired username to reset in the
Username
field and select "Reset Password" - Switch to the terminal where the service is running, and watch for the reset token message in the terminal, like so:
[2024-04-24T03:42:56Z DEBUG api_directory::auth::repo] New password reset c9k1zsftwki8q1hxinj0 created for user 4sw7q3z0w8ao6jtnzph7
- Take the reset token ID and append it to the reset password url, like so:
https://apigateway.local/reset-password/c9k1zsftwki8q1hxinj0
- In the form, provide the username, password, and password confirmation to reset the password.
- After resetting, a banner message should appear notifying the user that the password has been successfully reset.