~wegtam/smederee

~wegtam/smederee/README.md
 ..

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 EUPL version 1.2 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)
  • tokei (for detailed programming language statistics of repositories)

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:

  1. An RSA key is required recommended (support for ed25519 is experimental)!
  2. A custom port is used!
  3. Problems with newer SSH implementations due to changed scp (should be fixed)!

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

Endpoints only for guests

If an endpoint is intended to be used only by guests (users that are not logged in) then it should be implemented two times:

  1. a regular endpoint (HttpRoutes) with the intended implementation
  2. a protected endpoint (AuthedRoutes) with:
    • a simple redirect (SeeOther) or error page
    • put within a middleware with fall through

Endpoints for guests and users

Endpoints that provide functionality for both guests and users (logged in) should have their common logic extracted into a separate function and there should be two endpoints:

  1. a protected endpoint (AuthedRoutes) which calls the logic function
  2. a regular endpoint (HttpRoutes) which calls the logic function

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 use the provided sample configuration file:

% cat application.conf.sample > application.conf

Another option is to copy the default configuration:

% cat modules/hub/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 hub and tickets 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 default case is that the tickets simply use the configuration from the hub section which means you only have to care for the setup in the hub section.

The hub section has a ticket-integration section into which you have to enter the base uri under which the ticket endpoints are reachable. The ticket section has a hub-integration section with the analogue settings.

The hub section has 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:

  1. The schema is created beforehand by the administrator with the correct owner, for example: CREATE SCHEMA "hub" AUTHORIZATION smederee_hub;
  2. 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  TO ;

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

  1. Install colordiff
  2. Configure the $SMEDEREE_USER/.darcs/defaults file to contain the following line: 
    diff diff-command colordiff -rN -u %1 %2