Docker setup
#
PrerequisitesTo be able to use the development environment the following utilities should be available:
- Docker.
- docker-compose.
- Maven.
- A Java 11 JDK.
- Flutter.
#
Clone the repository and build the projectgit clone https://github.com/eellak/gsoc2021-sastixcmscd gsoc2021-sastixcmsmvn clean install
#
Setup MariaDB and Keycloak with docker-composeThe setup of MariaDB and Keycloak is done using docker-compose.
cd devops/dev-environmentdocker-compose up -d
This will bring up two containers, one for MariaDB and one for Keycloak which are already provisioned.
caution
You can change the values of the ports used in the .env file to avoid any conflicts. Default Keycloak and MariaDB passwords can be customized there, too.
#
Change the required configuration to the server propertiesYou can change the server configuration by editing the application.properties
files in
the src/main/resources
of the server
folder.
info
You should to change the following values:
- server.port: the development server's port (default is 9082).
- cms.volume: the folder where the cms will save the resources (you should avoid permission issues by specifying a user owned folder).
- spring.datasource.url: by default MariaDB is initialized in docker with a database named sastix_cms_docker. So if the docker-compose instructions are followed as described above the value provided should be jdbc:mysql://localhost:3306/sastix_cms_docker.
- keycloak.enabled: Set to true to use the default Keycloak configuration. If this is not changed the server will accept unauthenticated requests.
#
Spin up the spring-boot development serverIn the server
folder use:
mvn spring-boot:run
#
Spin up the Flutter clientTo run the Flutter client one needs to have Flutter installed on
one's system. The installation is described in the
documentation. After
installing Flutter you need to set the environment variables in the
assets/config/.env
file. Copying from the
assets/config/.env.example
file will start the Flutter application
using the default values for the Docker development environment.
caution
The FLUTTER_CLIENT_ID must be the same as the server Keycloak client.
The default development environment for it is cms-server
.
Flutter can work with devices, emulators and browsers. For example
the Chrome browser can be used by setting the CHROME_EXECUTABLE
environment variable to the Chrome executable.
After that the Flutter application for the web can be started with:
cd fclientflutter pub getflutter run -d chrome
#
Example usage#
Default Keycloak configurationBy using the default docker-compose (.env) values you could acquire a JWT token by:
curl -d "client_id=cms-server" -d "client_secret=6bdcbcb3-457c-4d86-b5c3-5b9cda7198da" -d "username=cms-admin" -d "password=cms-admin" -d "grant_type=password" "http://localhost:8080/auth/realms/CMS/protocol/openid-connect/token"
The default username/password combinations in the CMS realm are:
cms-admin / cms-admin , with role admincms-creator / cms-creator, with role creatorcms-consumer / cms-consumer, with role consumer
danger
The default configuration should never be used in production or on a publicly available URL. This is a major security issue.
#
Make an authenticated requestThe call above will provide a JSON response with an access JWT token and a refresh JWT token.
export TOKEN=<access_token>
- Check the API version information:
curl -X 'GET' 'http://localhost:9082/apiversion' -H 'accept: application/json' -v -H "Authorization: Bearer $TOKEN"
- Create a resource:
curl -v -X POST "http://localhost:9082/cms/v1.0/createResource" -H "accept: */*" -H "Content-Type: application/json" -d "{ \"resourceAuthor\": \"Test Author\", \"resourceExternalURI\": \"https://commons.wikimedia.org/wiki/Category:PNG_files#/media/File:Flederspekrp.png\", \"resourceMediaType\": \"image/png\", \"resourceName\": \"logo.png\", \"resourceTenantId\": \"zaq12345\"}" -H "Authorization: Bearer $TOKEN"
The requests are authenticated by checking the "Authorization: Bearer <access_token>" header. For more information refer to the authentication notes.
#
Login to the Swagger interfaceThe Swagger Interface is exposed to http://localhost:9082/swagger-ui.html
.
If Keycloak is enabled you will be redirected to the Keycloak interface and after you login you will be able to use the API interface to make authenticated requests.