Smederee (low german: forge/smithy)
A frugal platform which is dedicated to help people build great software together.
License
This code is licensed under the GNU Affero General Public License 3.0 or
later, see the LICENSE file for details.
System requirements
- Java 17 (or higher)
- PostgreSQL 13 (or higher)
- The time zone of the DBMS is expected to be set to
Etc/UTC
!
- Darcs
- colordiff (for coloured diffs)
Developer guide
For development and testing you need to install sbt.
Please see CONTRIBUTING.md for details how to to contribute
to the project.
During development you can start (and restart) the application via the reStart
sbt task provided by the sbt-revolver plugin.
Cloning via ssh has the following constraints currently:
- An RSA key is required!
- A custom port is used!
- Problems with newer SSH implementations due to changed
scp
!
Using a custom ssh port
To make darcs use the custom port either set the SSH_PORT
environment
variable (SSH_PORT=30983 darcs clone ...
) or configure your ssh client
accordingly in ~/.ssh/config
. Something like this should be sufficient:
# Only use configured identities even if there are more available.
IdentitiesOnly yes
IdentityFile ~/.ssh/id_ed25519
Host darcs.smeder.ee
IdentityFile ~/.ssh/id_rsa
Port 30983
User darcs
With such a configuration you should be able to use darcs clone
etc.
without having to set the environment variable.
Protecting endpoints
If an endpoint is intended to be used only by guests (users that are not
logged in) then it should be implemented two times:
- a regular endpoint (
HttpRoutes
) with the intended implementation
- a protected endpoint (
AuthedRoutes
) with:
- a simple redirect (
SeeOther
) or error page
- put within a middleware with fall through
Tests
Tests are included in the project. You can run them via the sbt task test
.
Be aware that the some tests might need a working database. These should be
tagged accordingly and can be excluded or included via the following
parameters for the test task:
--exclude-tags=NAME
(do not run any tests labelled with NAME
)
--include-tags=NAME
(do only run tests labelled with NAME
)
For example to not run any tests needing a database connection in the hub
module:
sbt:smederee> hub/testOnly -- --exclude-tags=NeedsDatabase
Deployment guide
Please ensure that the system requirements are met and that you have the
credentials needed to access the database.
Creating the distribution
On the sbt console run the task hub/Universal/packageXzTarball
which will
create a package under modules/hub/target/universal
. This archive can be
extracted to a place of your liking. Afterwards you have to create the
file conf/application.conf
in which you configure the service.
Creating the configuration file
The easiest way is to simply concatenate the both default configurations for
the hub and ticket module:
% cat modules/hub/src/main/resources/reference.conf \
modules/tickets/src/main/resources/reference.conf > application.conf
Important configuration settings
The first and foremost settings are the ones related to the database. Please
ensure that both database settings (hub and tickets) are set to proper
values.
Secondly take a look at the external
configuration settings for both
services and configure them accordingly to be able to reach them depending
on your setup. We assume that you will be running them behind a reverse
proxy which also does take care of encryption (https). Depending on your
setup you can either decide to run both endpoints under one domain or on
different subdomains e.g. hub on "example.com" and tickets on
"tickets.example.com".
The hub service has a ticket-integration
section into which you have to
enter the base uri under which the ticket endpoints are reachable. The
ticket service has a hub-integration
section with the analogue settings.
Both services have a cookie-secret
setting that MUST be set to a randomly
generated sequence of at least 64 alphanumeric characters.
Next you might want to check the pre-configured paths and make adjustments
were needed.
Database setup
The application uses schemas which may reside in a single database or not
but it is important that the configured database users have all necessary
permissions on that schemas. This can be achieved in a multitude of ways:
- The schema is created beforehand by the administrator with the correct
owner, for example:
CREATE SCHEMA "hub" AUTHORIZATION smederee_hub;
- The database is owned by the user and the schema will be created on the
first application start automatically.
Please note that different users (modules) sharing the same database (which
is possible due to the schema separation) need CONNECT
and CREATE
permissions on the database.
GRANT CONNECT, CREATE ON DATABASE <database name> TO <role name>;
Reverse proxy setup
It is advised to run the service behind a reverse proxy like nginx^6. The
configuration is pretty straight forward and should not require any tweaking:
server {
# Your server configuration (servername, ssl, etc.)
# ...
# The actual reverse proxy configuration:
location / {
proxy_pass http://localhost:8080;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
}
}
Please note that you will have to adjust the proxy_pass
part (hostname and
port) if you're running the service on another interface or port.
Coloured diffs
- Install
colordiff
- Configure the
$SMEDEREE_USER/.darcs/defaults
file to contain the following line:
diff diff-command colordiff -rN -u %1 %2