Skip to main content

Getting started

This guide contains general information on the steps required to configure and run the DES web server and background worker.

For a complete example setup running DES on kubernetes, please also see our dreams-k8s-example repository.

Prerequisites​

At least the following dependencies need to be provisioned and accessible:

  • A Postgres database (minimum version 15)
  • Mountable container volumes or an S3-compatible object storage

Getting the image​

The latest DES image can be pulled from quay.io/dreamstech/des:latest (ask Customer Success for access).

Here's an example using the docker cli tool:

docker login \
  -u=<username-supplied-by-doconomy> \
  -p=<token-supplied-by-doconomy> \
  quay.io

docker pull quay.io/dreamstech/des:latest

Preparing the DB​

Before you start​

The DATABASE_URL contains all necessary information to communicate between the database server and the container. This has the form of postgres://username:password@address:port/database-name

Using it you can control various additional things like forcing SSL. Example of turning on the above would be:

postgres://username:password@address:port/database-name?force_ssl=true

You can fine tune the database connection up to a certain degree thanks to it. You can read more about postgres connection string here.

Permissions​

The user credentials you set in the DATABASE_URL need to correspond with a user that has certain permissions on the database schema. For our app to work we require that the user can perform following operations:

  • Create, Read, Update and Delete tables on the schema
  • Create, Read, Update and Delete rows on the tables in the schema

Please remember that in postgres 15 the public schema is not by default accessible to all users

It's important that the database schema name is the same as the username in order for the connection string to work without any changes.

Everything in one go​

The DES image contains a script to initialize the database with the required schema: ./docker/self-hosted/setup.sh

Split the steps​

If you have a database created beforehand you can just use ./docker/self-hosted/db-setup.sh that contains only the schema load script. It won't try to create the database.

Example​

Here's an example using the docker cli, assuming that all necessary environment variables (see separate document) can be found in a file called .env:

docker run \
  --env-file .env \
  quay.io/dreamstech/des:latest \
  ./docker/self-hosted/setup.sh

Setting up storage​

File system based storage​

How to specifically set up and configure shared container volumes is up to you, the integrator. Ultimately you will need to mount a volume to the DES container path /app/storage with read and write permissions to the container user alpine.

Creating the S3 Active Storage Files bucket​

DES requires a single bucket to exist for content used by the app such as for example savehack and dream inspiration images. The name of the bucket is configurable with environment variables, see the environment variables section for details.

The following access policies are recommended:

  • DES should be allowed to ListBucket, PutObject, GetObject, and DeleteObject.
  • Objects should be available to the public only through signed download links created by DES.

S3-compatible storage other than AWS​

There are object storage service alternatives to AWS S3, both provided as SaaS and self-hosted, which are still compatible with S3 API. See the environment variables section for details on how to configure DES to work with such services.

Running the Web server​

To run the Web server container, use:

  • Command: ./docker/self-hosted/run-web-server.sh
  • Environment variables: See separate document.
  • Port mapping: expose the port you've set as the PORT environment variable

Here's an example using the docker cli tool:

docker run \
  --env-file .env \
  -p 3000:3000 \
  quay.io/dreamstech/des:latest \
  ./docker/self-hosted/run-web-server.sh

Background worker​

The Background worker takes care of all of the heavy lifting that happens outside of the request-response cycle. Its responsibilities include managing the business logic of all savehacks.

To run the Background worker container, use:

  • Command: ./docker/self-hosted/run-background-worker.sh
  • Environment variables: Same as for the Web server, see separate document.
  • Port mapping: none

Again, here's an example using the docker cli tool:

docker run \
  --env-file .env \
  quay.io/dreamstech/des:latest \
  ./docker/self-hosted/run-background-worker.sh

Setting up a new Partner​

In order to be able to do anything useful with the Web server, you need to have (at least) one Partner configured. In order to seed DES with your first Partner, SSH into a running container (either Web server or Background worker) and run the following script:

bundle exec rake dreams:partner:create -- \
  --name=<name of this partner> \
  --organization=<name of your organization> \
  --subdomain=<DNS-compatible subdomain for this partner> \
  --locales=<comma-separated list of locales> \
  --currency=<ISO 4217 code> \
  --admin_email=<email address for a bootstrap admin user>

The required arguments are:

  • name: is only used informally in DEPo and can be any unicode string, including whitespaces. Example value “Acme Bank Inc. SE”
  • organization: is a common label for a set of Partners. It should only contain alphanumerical characters and [_,-]. Example value: “acme-bank-inc”. Partners within the same organization are allowed to share certain content under certain circumstances. Ask customer success for more information on these capabilities for advanced partner setups.
  • subdomain: The subdomain this Partner will accept requests to (see Subdomain-based Routing above.)
  • locales: is a comma-separated list of ISO 639-1 2-letter language codes the Web app should support. Example value: “en,sv”. Note that locale codes including regions, such as en-GB, are not supported by design, as market-specific content and translations should reside under separate Partners instead.
  • currency: ISO 4217 currency code. Example value: “EUR”
  • admin_email: The email address for a first admin user that will be bootstrapped for the Partner. It is important that this email address can receive emails to be able to reset the password etc. later.

The output of running bundle exec rake dreams:partner:create will contain a temporary password for the first admin user.

Logging in to DEPo​

To verify that everything works as expected, you should now be able to access DEPo and login with your bootstrapped admin user.

  • Open your favorite browser and go to <subdomain>.<ROOT_URL>/depo, where subdomain is the subdomain you chose for your first Partner above, and ROOT_URL is the root url where you are hosting DES.
  • Log in using the admin email provided in the step above, and the temporary password

NOTE: You should change the auto-generated password, as it has been leaked to your console. Click on your avatar in the upper right corner, go to Account Settings, and click "change password".