Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • documentation/doc
  • PhilH/doc
  • louis.csn/doc
  • fabien4vo/doc
  • rngadam/doc
  • anastasia/doc
6 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 804 additions and 1089 deletions
source/import_documentation/devops/develop_sib_components.rst deleted 100644 → 0
View file @ 7af8b6eb
Develop SIB components
======================
FIXME: complete this section
source/import_documentation/devops/develop_sib_ldp_packages.rst deleted 100644 → 0
View file @ 7af8b6eb
Develop SIB server packages
===========================
Requirements
------------
- A `SIB server <./install_sib_server>`__ in development mode
Create your package
-------------------
From the project directory (the folder where the ``manage.py`` resides)
create a new package structure:
::
$ sib startpackage mypack
Add your package to the ``packages.yml``:
::
ldppackages:
mypack: mypack
Then initiate your server backend:
::
$ sib install sib_server
Note: It is important to run this command from the project directory in
order for the manager to find your package.
Finally, you can run your server as usual to see your new package’s
data.
source/import_documentation/devops/home.rst deleted 100644 → 0
View file @ 7af8b6eb
Startin’Blox operational documentation
======================================
``SIB`` application capabilities relies on:
- Servers with ``LDP packages`` able to serve the data
- Clients with ``components`` able to manipulate the data
The SIB servers
---------------
Before deploying any SIB applications you will need SIB servers able to
provide all capabilities your application relies on.
SIB servers come with packages developed and `maintained by the
Startin’Blox
team <https://git.happy-dev.fr/startinblox/djangoldp-packages>`__. You
can pick up the ones you like or write your own.
Install a SIB server
~~~~~~~~~~~~~~~~~~~~
You can use any servers exposing data as LDP containers. But you will
likely setup your own to expose your data to others.
- `How to setup a SIB server <./install_sib_server>`__
Develop your own server packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
LDP packages represent capabilites the server could support. Each may
have it’s own configuration depending of what mission it fulfills. There
is no limit of what a LDP package can do.
- `How to develop LDP packages <./develop_sib_ldp_packages>`__
The SIB applications
--------------------
SIB applications are only HTML code binding together web components to
provide all the functionalities the application requires. Each component
can connect to multiple LDP servers providing the matching
functionality. As for the server packages, some SIB components are
developed and `maintained by the Startin’Blox
team <https://git.happy-dev.fr/startinblox/components>`__ but you can
write your owns.
Create an app with SIB components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- `How to develop a SIB application <./develop_sib_application>`__
Developing your own components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When developing a new SIB application you can use existing components or
create your owns.
- `How to develop SIB components <./develop_sib_components>`__
Build an existing SIB application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The easiest to start with is to use an existing SIB application and
build it with your own configuration.
- `How to build an existing SIB
application <./build_sib_application>`__
SIB with Gitlab CI
------------------
- `How to set up automatic delivery for a SIB
application <./setup_continous_delivery_for_sib_application>`__
- `How to set up automatic delivery for
NPM <./setup_continous_delivery_for_node>`__
- `How to set up automatic delivery for
Pypi <./setup_continous_delivery_for_python>`__
SIB in docker
-------------
- `How to run SIB in docker containers <./sib_in_containers>`__
Contributing
------------
- `Architecture overview <./architecture_overview>`__
- `Convention for commit messages <./commit_message_convention>`__
- `Release workflow <./release_workflow>`__
- How to merge ``alpha`` in ``master`` ?
- How next ``alpha`` release is elected ?
Architecture
~~~~~~~~~~~~
Some general schema of the existing StartinBlox applications
architecture can be found
`here <https://docs.google.com/presentation/d/1iCRGaJpFvZjhjIUnpsn6lRTJJ31ES6n94BNkJygzUwM/edit?usp=sharing>`__.
source/import_documentation/devops/index.rst deleted 100644 → 0
View file @ 7af8b6eb
Devops
==========
.. toctree::
:maxdepth: 2
:caption: Devops:
build_sib_application
commit_message_convention
deploy_sib_application_on_alwaysdata
develop_sib_application
develop_sib_components
develop_sib_ldp_packages
home
install_sib_server
manually_force_pushing_on_regitries
migrate_gitlab
release_workflow
setup_continous_delivery_for_node
setup_continous_delivery_for_python
setup_continous_delivery_for_sib_application
sib_in_containers
tests/node_release_management
\ No newline at end of file
source/import_documentation/devops/install_sib_server.rst deleted 100644 → 0
View file @ 7af8b6eb
How to install a SIB server
===========================
Requirements
------------
The SIB server requires:
- python 3.6
- postgresql database (for production)
Initiate the server
-------------------
From a fresh environment, get the last version of the ``sib-manager``:
::
$ python -m pip install -U sib-manager
Create a project structure from a production template:
::
$ sib startproject sibserver --production
$ cd sibserver
For a development server remove the ``--production`` flag.
Configure your LDP packages
---------------------------
The configuration of the packages goes in ``packages.yml`` file in the
``ldppackages`` section. Those following ones are given as an example.
Yours depend on what your app does.
::
ldppackages:
djangoldp_circle: djangoldp_circle
djangoldp_account: djangoldp_account
djangoldp_profile: djangoldp_profile
oidc_provider: 'git+https://github.com/jblemee/django-oidc-provider.git@develop'
Details about ``packages.yml`` format are given in the template file.
Configure your server parameters
--------------------------------
The ``packages.yml`` files is also use to provide parameters to the
server itself.
Configure the server parameters in the ``packages.yml``:
::
server:
site_url: 'http://localhost:8000'
admin_email: admin@example.org
admin_name: admin
admin_pass: admin
This configuration works for a local development server but for a
production instance you need to setup a postgresql database and
configure dependent services:
::
server:
site_url: 'https://api.batman.happy-dev.fr'
allowed_hosts:
- api.batman.happy-dev.fr
db_host: postgresql-batman.happy-dev.fr
db_name: batman_db
db_user: batman
db_pass: changeit
smtp_host: smtp-batman.happy-dev.fr
smtp_user: batman
smtp_pass: changeit
admin_email: admin@example.org
admin_name: admin
admin_pass: changeit
xmpp_url: 'https://jabber.happy-dev.fr'
jabber_host: 'happy-dev.fr'
Launch the installation
-----------------------
Install/update the project:
::
$ sib install server
Launch the server
-----------------
Run the server in development:
::
$ python manage.py runserver 0.0.0.0:8000
To *launch the server in production*:
- you have to install the static files with
``python manage.py collectstatic``
- and you have to configure your python server to server the script:
``wsgi.py`` on the URL ``api.batman.happy-dev.fr/``.
Tips & tricks
-------------
Activate debug mode
^^^^^^^^^^^^^^^^^^^
To activate the debug mode (default in development) you can override
manually the ``DEBUG`` variable in the ``settings.py``
Install the server as a subfolder URL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This method isn’t officially supported and requires to change values in
the core configuration.
To setup the SIB server on a subfolder
``https://batman.happy-dev.fr/api`` you have to manually override the
configuration in the ``settings.py``:
::
BASE_URL = 'https://batman.happy-dev.fr'
SITE_URL = 'https://batman.happy-dev.fr/api'
STATIC_URL = '/api/static/'
and URLs in ``urls.py``:
::
urlpatterns = [
url(r'^api/', include('djangoldp.urls')),
url(r'^api/admin/', admin.site.urls),
]
Note: Alwaysdata static config ``/api/static/=/static/``
source/import_documentation/devops/manually_force_pushing_on_regitries.rst deleted 100644 → 0
View file @ 7af8b6eb
Manually force pushing on registries
====================================
**Tested for NPM only**
This a ``emergency`` procedure to force pushing on registries. It’s made
to be used when ``continuous delivery pipeline`` is down.
Requirements: This procedure requires authentication on the registries.
After you made your fix, determine the package version to release
(incremented from the last):
::
$ git pull --tags
$ git tag -l
v2.1.0
v2.2.0
Tag the new version to release first and update remote:
::
$ git tag -a 'v2.1.1'
$ git push --follow-tags
This step is important to keep coherency with the autorelease mecanism.
Edit the ``package.json`` to indicate to the registry the version we are
pushing:
::
$ vi package.json
{
"name": "plup-hello",
"version": "v2.1.1",
[truncated]
Push on regitry:
::
$ export NPM_TOKEN=<token>
$ echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > .npmrc
$ npm publish
And then reset the version as it is normally managed automatically:
::
$ git checkout -f
$ rm .npmrc
source/import_documentation/devops/migrate_gitlab.rst deleted 100644 → 0
View file @ 7af8b6eb
Gitab migration process
=======================
For LDP package release
-----------------------
- Reference to the `configuration
doc <./setup_continous_delivery_for_python#configure-project-on-gitlab>`__
1. Create the new project on https://git.startinblox.com by importing
the existing one from https://git.happy-dev.fr
2. Check the points 2 to 5 of the configuration doc (this is normaly
imported with the project)
3. Apply the point 6 of the configuration doc (variables aren’t
imported)\*
4. Clone the new project or update your remote in your local copy (ex:
``git remote set-url origin git@git.startinblox.com:djangoldp-packages/djangoldp-project.git && git pull``)
5. Update the ``.gitlab-ci.yml`` according to the configuration doc
6. Archive the project on the old gitlab
Note: (*) values for variables can be found in the original project
source/import_documentation/devops/release_workflow.rst deleted 100644 → 0
View file @ 7af8b6eb
Releases workflow
=================
- Public: SIB devs
Overview of the code release flow
---------------------------------
.. figure:: ../../_static/images/import_documentation/devops/docs/code_release_flows.png
:alt: code release flows
code release flows
Delivering applications
-----------------------
The applications delivery works with multiple levels of validation:
- Unit testing is automatically triggered for ``all`` branches
- Integration phase is manually triggered on ``feature/*`` branches
- Acceptance phase starts automattically when pushing/merging on
``master`` branch
- Live deployment is manually executed after acceptance on ``master``
branch
.. figure:: ../../_static/images/import_documentation/devops/docs/deployment_pipeline.png
:alt: deployment pipeline
deployment pipeline
Use the ``Pipelines`` menu to control deployment over test environments:
.. figure:: ../../_static/images/import_documentation/devops/docs/test_environments.png
:alt: Test environments
Test environments
And staging + production environments:
.. figure:: ../../_static/images/import_documentation/devops/docs/staging_environments.png
:alt: Staging environments
Staging environments
You can use the ``Environments`` section to track the versions deployed
across environments.
.. figure:: ../../_static/images/import_documentation/devops/docs/all_environments.png
:alt: Environments overview
Environments overview
Working with alpha branches
---------------------------
How to make a hotfix on stable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Propose a hotfix from ``master`` branch:
::
$ git checkout master
$ git checkout -b hotfix/something
# work work work
$ git commit
$ git push -u origin hotfix/something
Then make a proper ``merge request`` into ``master``.
How to make a new stable release from alpha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``master`` branch only accepts ``fast forward`` merges. So it is
necessary to prepare the prerelease branch in order to make such merges:
::
$ git pull --all
$ git checkout alpha
$ git merge master
$ git push
Then make a proper ``merge request`` into ``master``.
How to set the next prerelease version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The next prelease version is decided by parsing the commit messages
(like normal release) on the next push. Once the prerelease level is set
it is kept until the next release.
Force a bump (according to the configured release rules):
::
$ git checkout beta
$ git commit --allow-empty -m 'minor: force minor bump for beta'
$ git push
If the first commit pushed doesn’t trigger the wanted bump. You still
can delete all prerelease published tags since last stable on gitlab and
the corresponding publication on NPM registry.
Then you can make a commit with the appropriate message and push again.
source/import_documentation/devops/setup_continous_delivery_for_node.rst deleted 100644 → 0
View file @ 7af8b6eb
Setup Gitlab CI/CD for a Node package
=====================================
- Public: developers
- Reading: 5 minutes
Configure project on gitlab
---------------------------
This step requires ``maintainer`` profile on the project.
1. CHeck the ``autodeploy`` user has a ``maintainer`` profile on the
group or project (``Members``)
2. Protect the ``master`` branch allowing only ``maintainers`` to merge
and push (``Settings > Repository > Protected branches``)
3. Allow ``fast forward merge`` only
(``Settings > General > Merge Requests``)
4. Allow ``merge only if the pipeline succeeds``
(``Settings > General > Merge Requests``)
5. Configure ``pipeline strategy`` to ``clone``
(``Settings > CI/CD > Pipelines``)
6. Configure CI/CD variables for authentication
(``Settings > CI/CD > Environment variables``):
============= ============== ==========
Variable Value Protection
============= ============== ==========
``GL_TOKEN`` ``**********`` protected
``NPM_TOKEN`` ``**********`` protected
============= ============== ==========
\*****: Ask to devops for tokens.
Notes:
- The ``fast forward merges`` are mandatory for **prereleases**.
- The ``merge only if the pipeline succeeds`` only makes sense if there
is **unit testing**.
Configure project in code
-------------------------
Release management
~~~~~~~~~~~~~~~~~~
Configure the code packaging by adding a ``release`` section in
``package.json``:
::
$ vi package.json
{
"name": "<your package>",
"version": "0.0.0",
"repository": {
"type": "git",
"url": "https://git.startinblox.com/<path/to/package>.git"
},
"release": {
"branches": [
"master",
{"name": "alpha", "prerelease": true}
],
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular",
"releaseRules": [
{"type": "major", "release": "major"},
{"type": "minor", "release": "minor"},
{"type": "*", "release": "patch"}
]
}],
"@semantic-release/release-notes-generator",
"@semantic-release/gitlab",
"@semantic-release/npm"
]
}
}
Notes:
- Replace ``<your package>`` by the name of your package.
- The ``version`` will be automatically set at deployement step.
References:
- https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration
Pipeline execution
~~~~~~~~~~~~~~~~~~
Configure pipeline execution in repository:
::
---
image: node:11
stages:
- test
- release
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- tags
tags:
- sib
publish:
stage: release
before_script:
- npm install -g semantic-release@v17 @semantic-release/gitlab
script:
- semantic-release
only:
- master
- alpha
tags:
- deploy
IMPORTANT: Don’t forget to replace the ``Make your tests here !`` with
the relevant tests for your project. Not testing your application
automatically completly defeat the concept of continuous delivery !
Push configuration
------------------
Send to remote:
::
$ git add .
$ git commit -m 'feature: configured releases'
$ git tag -a v0.1.0 -m 'initial version'
$ git push --follow-tag
Setup prerelease on existing branch
-----------------------------------
Create an ``alpha`` branch from existing ``dev`` branch:
::
$ git pull --all
$ git checkout dev
$ git checkout -b alpha
$ git merge master
$ git push -u origin alpha
source/import_documentation/devops/setup_continous_delivery_for_python.rst deleted 100644 → 0
View file @ 7af8b6eb
Setup Gitlab CI/CD for a Pip distribution
=========================================
- Public: developers
- Reading: 5 minutes
Configure project on gitlab
---------------------------
This step requires ``maintainer`` profile on the project.
1. Check the ``autodeploy`` user has a ``maintainer`` profile on the
group or project (``Members``)
2. Protect the ``master`` branch allowing only ``maintainers`` to merge
and push (``Settings > Repository > Protected branches``)
3. Allow ``fast forward merge`` only
(``Settings > General > Merge Requests``)
4. Allow ``merge only if the pipeline succeeds``
(``Settings > General > Merge Requests``)
5. Configure ``pipeline strategy`` to ``clone``
(``Settings > CI/CD > Pipelines``)
6. Configure CI/CD variables for authentication
(``Settings > CI/CD > Environment variables``):
================= =============== ==========
Variable Value Protection
================= =============== ==========
``PYPI_USERNAME`` ``startinblox`` protected
``PYPI_PASSWORD`` ``**********`` protected
``GL_TOKEN`` ``**********`` protected
================= =============== ==========
\*****: Ask to devops for tokens.
Notes:
- Python projects doesn’t support **prereleases**.
- The ``merge only if the pipeline succeeds`` only makes sense if there
is **unit testing**.
Configure project in code
-------------------------
Release management
~~~~~~~~~~~~~~~~~~
Add ``__version__`` variable somewhere in ``__init__.py``:
::
__version__ = '0.0.0'
Create a file ``setup.cfg`` at the root of your project, alongside the
directory of your app. Configure code packaging by adding a
``semantic-release`` section:
::
[metadata]
name = <your package>
version = attr: <your package>.__version__
description = StartinBlox package
long_description = file: README.md
long_description_content_type = text/markdown
license = MIT
classifiers =
Programming Language :: Python :: 3
[options]
packages = find:
[semantic_release]
version_source = tag
version_variable = <your package>/__init__.py:__version__
commit_parser = commit_parser.parse
Create a file ``.gitlab-ci.yml`` at the root of the project, alongside
the previous one. Edit it to configure pipeline execution in repository:
::
---
image: python:3.6
stages:
- test
- release
# this stage only make sense if you have unit tests
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- tags
tags:
- test
publish:
stage: release
before_script:
- pip install python-semantic-release~=5.0 sib-commit-parser~=0.3
- git config user.name "${GITLAB_USER_NAME}"
- git config user.email "${GITLAB_USER_EMAIL}"
- git remote set-url origin "https://gitlab-ci-token:${GL_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
- git fetch --tags
script:
- semantic-release publish
only:
- master
tags:
- deploy
Push configuration
------------------
Send to remote:
::
$ git add .
$ git commit -m 'feature: added gitlab CI'
$ git tag -a v0.1.0 -m 'initial version'
$ git push --follow-tag
source/import_documentation/devops/setup_continous_delivery_for_sib_application.rst deleted 100644 → 0
View file @ 7af8b6eb
Deploy your SIB application
===========================
Requirements
------------
In order to run your application you have to configure your web serveur
to serve a static folder (let say ``www``). The configuration itself
depends on your hosting provider.
Set up SSH authentication on your server
----------------------------------------
Generate a keypair (or use an existing one):
::
$ ssh-keygen -t ecdsa -f gitlabci -N '' -C 'deploy@gitlab'
And copy the public key to your server:
::
$ ssh-copy-id -f -i gitlabci.pub <user>@<server>
Pipeline deployment with Gitlab CI
----------------------------------
Configure the ``APP_CONFIG`` variable in the Gitlab pipeline. It is a
JSON string of the configuration file you can generate with
``jq -c . config.json``.
In a ``.gitlab-ci.yml`` file:
::
image: node
stages:
- deploy
deploy_staging:
stage: deploy
environment: staging
script:
- echo "$APP_CONFIG" > config.json
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' > gitlab.key && chmod 600 gitlab.key
- npm install
- npm run build
- scp -i gitlab.key -o StrictHostKeyChecking=no -r dist/* <user>@<host>:~/www/
only:
- staging
source/import_documentation/devops/sib_in_containers.rst deleted 100644 → 0
View file @ 7af8b6eb
SIB in docker containers
========================
This is not intended to support production running.
Setup your SIB server
---------------------
1. Create your ``packages.yml`` according to the documentation.
2. Create the ``Dockerfile``:
::
FROM python:3.6
ENV PATH="/root/.local/bin:${PATH}"
RUN pip install --user -U sib-manager
WORKDIR /opt
RUN cd /opt/ && sib startproject sib_server
ADD packages.yml /opt/sib_server/packages.yml
RUN cd /opt/sib_server && sib install sib_server
EXPOSE 8000
CMD cd /opt/sib_server && python manage.py runserver 0.0.0.0:8000
3. Build the image:
::
# docker build -t sibserver .
4. Run the container:
::
# docker run --rm -p 127.0.0.1:8000:8000 -d sibserver
Serve your client app
---------------------
Launch a container from within your code folder:
::
# docker run --rm -v $PWD:/code -w /code -u $UID -it -p 127.0.0.1:3000:3000 node npm install && npm run watch
source/import_documentation/devops/tests/node_release_management.rst deleted 100644 → 0
View file @ 7af8b6eb
Test version releases with node
===============================
Configure release management
----------------------------
Confiugre semantic release in project:
::
$ vi package.json
{
"name": "siblab",
"version": "0.1.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"release": {
"branches": [
"master",
{"name": "alpha", "prerelease": true}
],
"plugins": [
"@semantic-release/commit-analyzer"
]
}
}
Setup with gitlab-CI:
::
$ vi gitlab-ci.yml
---
image: node
stages:
- test
- release
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- master
- tags
publish:
stage: release
before_script:
- npm install -g semantic-release@v17 @semantic-release/gitlab
- git checkout $CI_COMMIT_REF_NAME
script:
- semantic-release
only:
- master
- alpha
Test the commit publication in docker
-------------------------------------
::
$ docker run -v $PWD:/code -w /code --name testnode -it node bash
# npm install -g semantic-release @semantic-release/gitlab
# export GL_URL='https://git.startinblox.com'
# export GL_TOKEN=<token>
# export NPM_TOKEN=<token>
# semantic-release --dry-run
Test the prerelease workflow
----------------------------
Patching on alpha
~~~~~~~~~~~~~~~~~
Make a first patch on alpha:
::
$ git commit -m 'init: initial commit'
$ git tag -a v0.1.0 -m v0.1.0
$ git checkout -b alpha
$ git commit --allow-empty -m 'feat: first commit on alpha1'
$ git push --all --follow-tags
Results for ``master`` pipeline:
::
ℹ Found git tag v0.1.0 associated with version 0.1.0 on branch master
ℹ Analyzing commit: fix: hotfix on master
ℹ The release type for the commit is patch
ℹ Analysis of 1 commits complete: patch release
ℹ The next release version is 0.1.1
✔ Created tag v0.1.1
Results for ``alpha`` pipeline:
::
ℹ Found git tag v0.1.0 associated with version 0.1.0 on branch alpha
ℹ Analyzing commit: feat: first commit on alpha1
ℹ The release type for the commit is minor
ℹ Analysis of 1 commits complete: minor release
ℹ The next release version is 0.2.0-alpha.1
✔ Created tag v0.2.0-alpha.1@alpha
Repository after pipelines executions:
::
$ git log --graph --oneline --all --decorate --date-order
* ae5d4a8 (HEAD -> master, tag: v0.1.1, origin/master) fix: hotfix on master
| * 19e6aa9 (tag: v0.2.0-alpha.1@alpha, origin/alpha, alpha) feat: first commit on alpha1
|/
* 19a5d24 (tag: v0.1.0) init: initial commit
Increment patching:
::
$ git checkout alpha
$ git commit --allow-empty -m 'fix: keep working on alpha'
Results for ``alpha`` pipeline:
::
ℹ Found git tag v0.2.0-alpha.1@alpha associated with version 0.2.0-alpha.1 on branch alpha
ℹ Analyzing commit: fix: keep working on alpha
ℹ The release type for the commit is patch
ℹ Analysis of 1 commits complete: patch release
ℹ The next release version is 0.2.0-alpha.2
✔ Created tag v0.2.0-alpha.2@alpha
Merging alpha in master
~~~~~~~~~~~~~~~~~~~~~~~
Merging ``alpha`` in ``master`` triggers the version bump by analyzing
the new commits from ``alpha`` branch. When pushing again in ``alpha``
branch the new tag ``v0.2.0`` is not in the ``alpha`` history, so it
keeps incrementing from previous release.
To make the version bump available on ``alpha`` there is 2
possibilities:
1. Allow only fast forward merge in ``master``:
::
$ git checkout master
$ git merge --ff-only alpha
fatal: Not possible to fast-forward, aborting.
$ git checkout alpha
$ git merge master
$ git checkout master
$ git merge --ff-only alpha
Updating 70f176b..8563ed1
Fast-forward
**merge** ``master`` on ``alpha`` **before** fast forwarding ``alpha``
in ``master``
2. Merge back in ``alpha``:
::
$ git checkout alpha
$ git merge --ff-only master
Updating 4e3f382..a9e1eed
Fast-forward
**merge back** ``master`` on ``alpha`` **after** merging ``alpha`` in
``master``
Repository after pipelines:
::
$ git log --graph --oneline --all --decorate --date-order
* 96abdd6 (HEAD -> master, tag: v0.3.2, origin/master) fix: hotfix in master
| * d78a2ae (tag: v0.3.2-alpha.1@alpha, origin/alpha, alpha) fix: another fix on alpha
|/
* 8563ed1 (tag: v0.3.1) fix: another fix on alpha <-- in both histories (fast forward)
* 70f176b fix: hotfix on master
| * 17e24c3 (tag: v0.3.1-alpha.1@alpha) fix: another commit on alpha after merging back from master
|/
* a9e1eed (tag: v0.3.0) merge: branch 'alpha' <-- in both histories (merged back)
|\
| * 4e3f382 (tag: v0.2.0-alpha.4@alpha) feat: minor bump in alpha
| * 3674bd4 (tag: v0.2.0-alpha.3@alpha) fix: another fix on alpha
* | 5d513b0 (tag: v0.2.0) merge: branch 'alpha' <-- only in master history
|\ \
| |/
| * 4350b55 (tag: v0.2.0-alpha.2@alpha) fix: keep working on alpha
* | ae5d4a8 (tag: v0.1.1) fix: hotfix on master
| * 19e6aa9 (tag: v0.2.0-alpha.1@alpha) feat: first commit on alpha1
|/
* 19a5d24 (tag: v0.1.0) init: initial commit
- How next ``alpha`` release is set ?
- How to merge ``alpha`` in ``master`` ?
source/import_documentation/djangoldp_guide/djangoldp-references.rst 0 → 100644
View file @ 405339e9
DjangoLDP reference guide
#########################
The DjangoLDP commands
======================
.. code-block:: bash
$ djangoldp --help
Usage: djangoldp [OPTIONS] COMMAND [ARGS]...
DjangoLDP CLI
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
configure Configure the project.
initserver Start a DjangoLDP server.
install Install project dependencies.
runserver Run the Django embeded webserver.
startpackage Start a DjangoLDP package.
The `djangoldp` server is built ontop of `django` framework. The `django` core commands are also available. Check `python manage.py --help` and `the official Django documentation <https://docs.djangoproject.com/en/2.2/>`__.
The Initserver command
----------------------
This command initiate a new server folder from a template. It has the minimal option to work out of the box.
The Configure command
---------------------
This is a command meant to tell the server the settings have changed and it must run some maintenance operations and data integrity check, such as the model migration of the LDP packages.
It has options to create new administrator users during the configuration process.
The Install command
-------------------
This command parses the `dependencies` section of the configuration file and install all python distribution required by the project. It is a wrapper around the `requirements.txt` file.
The runserver command
---------------------
This command loads the configuration and starts the LDP server. It is a wrapper around the `django-admin runserver` command.
The startpackage command
------------------------
This a helper command working the same way the `django startpackage` does command. It creates a folder with a DjangoLPD package template.
The DjangoLDP configuration file
================================
The server comes with a default `settings.yml` you can customize.
It contains 3 main sections:
* `dependencies`: contains a list of dependencies to install with pip during the `install` phase
* `ldppackages`: contains a list of djangoldp packages to activate
* `server`: contains all the configuration required by djangoldp server
You need to restart the server after a change in configuration.
The Dependencies section
------------------------
This is not mandatory as you can install all your dependencies manually. But it is convienent to have all in one file when exchanging server configurations.
The format for dependencies is the one accepted by pip. For example:
.. code-block:: yml
dependencies:
- git+https://git.startinblox.com/djangoldp-packages/djangoldp-account.git
As for any python project when you declare a dependency you have to make sure it is installed. You can use the wrapper command `djangoldp install` for this.
The LDP packages section
------------------------
When you want to use a LDP package you need to reference it in the configuration. For example:
.. code-block:: yml
ldppackages:
- djangoldp_account
The name referenced there must be the name of the python module, the one your would use with the `import` statement.
Some packages may require some configuration to work properly. It is a good practice to run the `djangoldp configure` command after adding or upgrading a LDP package.
Here you have :
* `a list of all the package available <https://git.startinblox.com/djangoldp-packages/>`__
* `Explanation on how to make one <https://docs.startinblox.com/import_documentation/develop-sib-ldp-packages.html>`__
If the description of the available packages is unclear, open an issue to ask for more description.
The Server section
------------------
This section contains all parameters to the server itself. All this section is loaded as a Django configuration object to initialize the server.
see https://docs.djangoproject.com/fr/2.2/topics/settings/ for a detail explanation of all settings
The server parameters can be changed at different levels. They are overriden in the following order:
1. The DjangoLDP core default settings
2. :ref:`The DjangoLDP package settings`
3. The code from :ref:`the extra settings module`
4. The `server` section of the YAML settings file
Which means a value written in the server section of `settings.yml` will override any parameters given by the core or the djangoldp packages.
The `MIDDLEWARE` and `INSTALLED_APPS` parameters make exception to that behavior. Those lists are extended from previous values instead of being rewritten. When duplicated entries are detected in those settings, only the first items present in the list are kept.
The extra settings module
-------------------------
The `settings.yml` server section doesn't support dynamical configuration. When this is required, python code for configuration can also be loaded from a `settings.py` module along with the `settings.yml`.
The DjangoLDP package settings
==============================
The DjangoLDP packages support settings declaration through a special `djangoldp_settings.py` at the module's root. This file is fetched by the djangoldp core at runtime and all parameters are loaded following the settings resolution order. (see :ref:`The server section`)
.. code-block:: python
# cat mypkg/mypkg/djangoldp_settings.py
MIDDLEWARE = []
INSTALLED_APPS = []
MYPACKAGE_VAR = 'MY_DEFAULT_VAR'
source/import_documentation/djangoldp_guide/install-djangoldp-server.rst 0 → 100644
View file @ 405339e9
.. _djangoldp-guide-intro:
Get started with the DjangoLDP server
#####################################
What is behind the DjangoLDP server ?
=====================================
Startin'Blox is a front framework, based on a server named `DjangoLDP <https://git.startinblox.com/djangoldp-packages/djangoldp/>`__ and based on `Django <https://www.djangoproject.com/>`__.The DjangoLDP server is adapted to be compatible with Linked Data's convention.
As a reminder and as specified in :ref:`Startin'Blox presentation <sib-presentation>`, Startin'Blox is data source agnostic,
i.e. it adapts to data sources that are compatible with the Linked Data Platform conventions.
DjangoLDP server, used in production, is the most operational solution today. However, it is currently still
in development, so there is no guarantee that it is complete.
Also, work in progress on compatibility of Startin'Blox with Virtual Assembly's `SemApps <https://www.virtual-assembly.org/semapps/>`__ and Inrupt's `Community server <https://inrupt.com/Solid-roadmap-preview>`__.
Go to `Server Architecture <server-architecture.html>`_ to know more about it.
And check the `References guide <djangoldp-references.html>`__ to know all the details.
Requirements
============
The DjangoLDP server requires:
* python 3.11
* pip and virtualenv installed
* postgresql database (for production)
* sqlite3 (for development)
* Django 4.2
.. note::
If you're working on many project in Python, we advice you to use `a virtual environment <https://docs.python.org/3/library/venv.html>`__.
.. note::
`See the documentation to set it with Docker <https://docs.startinblox.com/import_documentation/install-sib-server.html#initiate-the-server-with-docker/>`__.
Optional: Set your virtual environment
=======================================
If you want to set a virtual environment, you can do it with the following commands:
.. code-block:: bash
cd /path/to/your/project
python -m venv myenv
source myenv/bin/activate
Install DjangoLDP
=================
From the virtual environment, get the last version of DjangoLDP:
.. code-block:: bash
python -m pip install djangoldp
Initiate a new server
=====================
Create a server workdir:
.. code-block:: bash
djangoldp initserver sibserver
cd sibserver
All the command must be issued from this working directory.
Add a package to your `settings.yml` file, let's start with `djangoldp_account`:
.. code-block:: yml
dependencies:
- djangoldp-account
ldppackages:
- djangoldp_account
The `server` section should work out of the box. Check the reference guide for details on the settings file.
Install the dependencies you just added:
.. code-block:: bash
djangoldp install
This downloads the `djangoldp-account` distribution from pypi.org.
Configure your backend to support the new package:
.. code-block:: bash
djangoldp configure --with-dummy-admin
This will also create a local admin user (not suited for production use).
Then launch the server:
.. code-block:: bash
djangoldp runserver
Then go to `http://localhost:8000/admin/ <http://localhost:8000/admin/>`__ to acces to your Django administration with the `admin` user and `admin` password.
You should be able to get you api at `http://localhost:8000/abc/` where abc is the model of data you want to get.
Start your own DjangoLDP package
================================
.. note::
A bug in with the local package loading breaks the Django migrations directory recognition. To workaround it, you need to start or move your DjangoLDP package outside the server workdir and make a symlink inside the working directory.
Start a new package in the server workdir parent directory:
.. code-block:: bash
djangoldp startpackage mypkg
From the server workdir create a symlink to the package python module:
.. code-block:: bash
cd sibserver
ln -s ../mypkg/mypkg mypkg
Then reference your new package in the `ldppackages` section:
.. code-block:: yml
ldppackages:
- mypkg
Don't forget to run the `configure` command if your package load django migrations.
source/import_documentation/server-architecture.rst → source/import_documentation/djangoldp_guide/server-architecture.rst
View file @ 405339e9
......@@ -2,7 +2,7 @@ Server Architecture
###################
DjangoLDP server
===============
================
Before deploying any SIB applications you will need SIB servers able to provide all capabilities your application relies on.
......@@ -18,7 +18,7 @@ DjangoLDP come with packages developed and maintained by the Startin'Blox team.
LDP packages
===========
============
Once you have your server DjangoLDP installed, you can plug to it DLP packages which are extention to treat a specific shape of data.
Each component has its own datas shapes. The server that will manage datas of a specific component has to get the specfic package related.
......@@ -33,7 +33,7 @@ You'll find the right package in the documentation of each component.
A request in detail
===================
.. figure:: ../_static/images/servers-of-the-future.png
.. figure:: ../../_static/images/servers-of-the-future.png
:alt: How we imagine the servers of the future
......
source/import_documentation/Solid-introduction.rst → source/import_documentation/first_step/Solid-introduction.rst
View file @ 405339e9
Our SOLID introduction
======================
`SOLID <https://solid.mit.edu/>`__, for SOcial LInked Data, is a project started in 2015 and led
in the 3WC by `Tim Berners Lee <https://fr.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
in the W3C by `Tim Berners Lee <https://en.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
the web who aims to rethink the way we build application in order to give back the power back to the final user.
For us SOLID project is above all a philosophy, a goal to reach and which inspires us.
For us SOLID project is above all a philosophy, a goal to reach and that inspires us.
Solid is built on top of existing Web standards. The core Solid specification relies on LDP and WAC (WAC draft, both being based on HTTP and RDF vocabularies. Solid also uses a subset of SPARQL UPDATE through HTTP PATCH queries. Identification in Solid is based on WebID-TLS and/or OIDC.
To know more on how does Solid relate to other Web standards, how a look to this `SOLID Faq <https://solidproject.org/faqs#how-does-solid-relate-to-other-web-standards>`__.
To know more on how does Solid relate to other Web standards, have a look to this `SOLID Faq <https://solidproject.org/faqs#how-does-solid-relate-to-other-web-standards>`__.
Let's have an overview on how we implement `SOLID specifications <https://github.com/solid/solid-spec>`__.
What is SOLID ?
---------------
It is a set of standards on which we agree internationally to communicate our applications between them. It is about the standardization of APIs.
It is a set of standards on which we agree internationally to enable our applications to communicate with each other. It is about the standardization of APIs.
.. warning::
This page should be improved. `Any feedbacks is welcome <https://mailto:alice@startinblox.com>`__
This page should be improved. `Any feedback is welcome`__.
.. _Any feedback is welcome: alice@startinblox.com
Our API
-------
......@@ -93,17 +95,17 @@ Did you notice the presence of a context ?
]
}
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__.
That’s mean that we encode `Linked
Data <https://en.wikipedia.org/wiki/Linked_data>`__ using Json.
Data <https://en.wikipedia.org/wiki/Linked_data>`__ using JSON.
JsonLD is an `RDF <https://en.wikipedia.org/wiki/RDF>`__ implementation,
which is its-selft the basic language of `semantic
which is itself the basic language of `semantic
web <https://en.wikipedia.org/wiki/Semantic_Web>`__.
.. warning::
We use for our API JsonLD but you can imagine use other implementation like Turtle or XML.
We use for our API JsonLD but you can imagine using other implementations like Turtle or XML.
This context allows you to link object properties in a JSON document to
concepts in an `ontology <https://en.wikipedia.org/wiki/Web_Ontology_Language>`__.
......@@ -139,7 +141,7 @@ Here is the context referred :
}
The type we use is ``foaf``. That means that we use the FOAF ontology
which is done to describe people.
which is designed to describe people.
If you go to the `foaf ontology <http://xmlns.com/foaf/0.1/>`__, you’ll
see that the properties which we can use are :
......@@ -157,7 +159,7 @@ status \| surname \| theme \| thumbnail \| tipjar \| title \| topic \|
topic_interest \| weblog \| workInfoHomepage \| workplaceHomepage \|
yahooChatID \|
Now we can describe a user for every machines in the world using a
Now we can describe a user for every machine in the world using a
universal language :)
Why JsonLD is awesome ?
......@@ -182,7 +184,7 @@ JsonLD allow us to us Linked Datas in a very intuitive way.
Let's speak about containers
----------------------------
So how JsonLD manage to tiny the datas ?
So how JsonLD manage to simplify the datas ?
Let’s have a look on this part :
......
source/import_documentation/faq.rst → source/import_documentation/first_step/faq.rst
View file @ 405339e9
......@@ -20,20 +20,20 @@ If you want to add/change something on this documentation, `here are the instruc
* **What is Solid?**
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <solid.mit.edu//>`__.
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <https://solid.mit.edu//>`__.
* **This is open source?**
The whole project is under `MIT licence <https://git.startinblox.com/framework/sib-core/blob/master/LICENSE/>`__.
* **Why the documentation is not in makdown?**
* **Why the documentation is not in markdown?**
This documentation in is `Restructured Text <https://docutils.sourceforge.io/rst.html>`__. `Have a look to this article <https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`__ if you want to understand our choice.
This documentation in is `Restructured Text <https://docutils.sourceforge.io/rst.html>`__. Have a look to `this article <https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`__ if you want to understand our choice.
* **You cannot find the question you have?**
`Send your question <https://mailto:alice@startinblox.com>`__ to the the maintainer of the doc or
`Send your question`__ to the maintainer of the doc or
`open an issue on the doc <https://git.startinblox.com/documentation/doc/-/boards/>`__.
.. _Send your question: alice@startinblox.com
\ No newline at end of file
source/import_documentation/first_step/get-started.rst 0 → 100644
View file @ 405339e9
.. _podcast-tutorial:
Getting Started : Startin'blox Podcast Tutorial
***********************************************
Presentation and Objectives
===========================
Startin'blox provides SOLID components called "blox" to build-up a website or a webapp that can consume and
manage data from various SOLID-compatible sources (to learn more :ref:`about Startin’blox components <about-our-components>`). This tutorial shows the various front-end blox available
in the framework and describe step-by-step how to use it to make a podcast reader and sharing application.
This application is build as a blox itself and can be embeded in a website by just dropping a
``<solid-podcast>`` tag in the page.
Here is the simple mockup that shows what the component will look like :
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Mockup-Podcast-Tutorial.png
:alt: Mockup Podcast
In this tutorial, we will use some `Radio France podcasts <https://www.franceinter.fr/podcasts-originaux>`__.
Feel free to use your own if you like.
Teaching Objectives
-------------------
* Learn what a data source is
* Use ``solid-display`` blox and understand the basic concepts about the consumed data
* Organise the listed items and use widgets to customize the display (fields, field sets, img, ...)
* Apply css to have your own look-and-feel
* Create custom widgets
* Plug js to have your own behavior
Semantic data source
====================
Before begining our journey, we need a semantic data source formatted in a way that the framework can
understand. The only supported format today in Startin'blox JSON Linked Data (`JSON-LD <https://json-ld.org/>`__).
But a vast majority of podcast feeds are provided in RSS format. So let's use a simple conversion tool
that will take a podcast RSS feed and format it to JSON-LD. You can find this little helper called
``rss2jsonld`` on `this git repository <https://git.startinblox.com/fabien4vo/rss2jsonld/>`__ or use directly the
bundled source from https://cdn.startinblox.com/tuto/rss2jsonld.js.
Setup the environment and display data
======================================
To use the Startin'blox framework, just embed it in the head of your html :
.. code:: html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<title>SiB tutorial - Podcast</title>
<script type="module" src="https://cdn.skypack.dev/@startinblox/core@0.15"></script>
<script src="https://cdn.startinblox.com/tuto/rss2jsonld.js"></script>
</head>
<body>
</body>
</html>
``core`` is the "heart" of the framework, and contains all the needed parts to get started. The current version
of the core is ``0.15.6`` at the time of writing. The third number will increase with each published improvement
and bugfix. Using ``@0.15`` at the end of the url will make it point to the latest bugfix available. The second
number ``15`` will increase when new feature or breaking change are introduced. If you remove the @15 from the
url, your application will get the next release as soon as it is published, but you probably have to change some
part of it to make it work with this new version. So specifying the version is safer.
The ``rss2jsonld`` script is here to automatically convert RSS data source to JSON-LD format.
We can now use our first blox : ``<solid-display>``. Startin'blox use the `HTML Custom Element specification <https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements>`__
which is part of the webcomponents standard, to create those blox. So you can use it as any other HTML tag,
like ``<video>`` or ``<select>``. This blox simply displays the data provided by the linked data source :
.. code:: html
<solid-display data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml" no-render/>
I use the ``no-render`` attribute so that the RSS XML feed is not loaded by startin'blox until it was converted
by ``rss2jsonld``.
The result is not very pretty : all fields are displayed in plain text without formatting :
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render1-Podcast-Tutorial.png
:alt: Data displayed without formatting
Organize and format data
========================
To put data in order, we use the ``fields`` tag :
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
no-render
fields="title, description"
/>
``fields`` take an ordered list of field names (found in the data source) and make the component to display only those fields in the provided order.
We can also use a **widget** to specify how each field must be shown :
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, description"
widget-title="h1"
no-render
/>
``widget-[field]`` take a HTML tag name and make the component use it to display this field.
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render2-Podcast-Tutorial.png
:alt: Data displayed with H1
It starts to look better !
Any HTML element can be used as widget, but Startin'blox also provide **built-in widgets** to easily manage specific
cases. To display images from their url, use the ``solid-display-img`` widget :
.. code-block:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, description"
widget-title="h1"
widget-image.url="solid-display-img"
no-render
/>
Fields can also be grouped in **sets** using brackets : each bracket opens or closes a group, and groups can be
nested. The word before the opening bracket is the group name and can be used to have a specific widget to display this group.
.. code-block:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta(itunes:author, itunes:category.text), description"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
no-render
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png
:alt: Data displayed with image
Apply CSS to have your own look-and-feel
========================================
``solid-display`` uses standard HTML to display the data, and that HTML can be styled with CSS.
.. code:: html
<style>
solid-display {
max-width: 800px;
display: block;
margin: auto;
}
solid-display img {
width: 200px;
float: left;
margin-right: 20px;
}
</style>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render4-Podcast-Tutorial.png
:alt: Data displayed, CSS added
You can also target specific field with an attribute selector because ``<solid-display>`` component adds a
``name="[field]"`` attribute to the displayed data.
.. code:: css
[name="itunes:category.text"]{
display: inline-block;
border: solid thin;
padding: 0.2em 0.5em;
margin: 0 1em;
border-radius: 0.5em;
}
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render5-Podcast-Tutorial.png
:alt: Data displayed, CSS added next
But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let's you specify a class name.
.. code-block:: html
<style>
.bordered {
display: inline-block;
border: solid thin;
padding: 0.2em 0.5em;
margin: 0 1em;
border-radius: 0.5em;
}
</style>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta(itunes:author, itunes:category.text), description"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
class-itunes:category.text="bordered"
no-render
/>
You can also use arbitrary text (enclosed by single quotes) in the fields list to display a text node :
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta('By: ', itunes:author, itunes:category.text), description"
[...]
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png
:alt: Data displayed, CSS and text enclosed by sigle quotes
Display nested list fields
==========================
Let's now display the informations about podcast episodes. They are listed in the ``item`` field, and as soon as it's
a list we have to tell the framework that it should be treated as multiple values.
This is achieved with the ``multiple-[field]`` attributes. This tag creates a nested ``<solid-display>`` for each entry in
``item``. ``multiple-[field]-fields`` attribute is used to control which nested fields are displayed for each item.
.. code-block:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, header(image.url, info( meta('By: ', itunes:author, itunes:category.text), description)), item"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
class-itunes:category.text="bordered"
widget-header="header"
multiple-item
multiple-item-fields="title"
no-render
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png
:alt: Add item in data displayed
Custom template
===============
To go further, we need to create our own widget template using the ``solid-widget`` tag. Let's show other episode data:
.. code-block:: html
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta(pubDate, itunes:duration), description"
widget-title="h2"
widget-description="p"
/>
</template>
</solid-widget>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
[...]
multiple-item="podcast-episode"
no render
/>
``solid-widget`` tag must be used with ``template`` to avoid its content to be rendered during the first page display.
The code included in the template is then used by Startin'blox to render each item. And you can use here again all the
attributes we juste learned, such as ``fields`` and ``widget-[field]``.
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render8-Podcast-Tutorial.png
:alt: Add custom template for item
Plug a bit of Javascript
========================
When a custom widget template is used, it gets a javascript variable called ``value`` that contains the resource. It can be
displayed directly in the template using ``${value}`` or you can apply some Javascript to it before. For example, here is how
to format the date using the browser locale settings :
.. code:: html
<solid-widget name="format-date">
<template>
<time datetime="${value}">${new Date(value).toLocaleDateString(undefined, {weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'})}</time>
</template>
</solid-widget>
Now if I use ``widget-pubDate="format-date"`` in ``<solid-widget name="podcast-episode">``, I get a nice formatted date :
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render9-Podcast-Tutorial.png
:alt: Plug JS in a solid-widget
And this template mechanism plays also nicely with other HTML5 standard tags, such as ``audio`` :
.. code:: html
<solid-widget name="audio-player">
<template>
<audio src="${value}" controls/>
</template>
</solid-widget>
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta('Épisode du ', pubDate, ' - ', itunes:duration), description, enclosure.url"
widget-title="h2"
widget-description="p"
widget-pubDate="format-date"
widget-enclosure.url="audio-player"
/>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png
:alt: Add audio player solid-widget
Conclusion
==========
This short tutorial has showed how to display the data from a podcast RSS feed using startin'blox framework. You can now
check this is working with other podcasts (provided that CORS headers are set on the server).
You can find the code on `this repository <https://git.startinblox.com/fabien4vo/solid-podcast>`__.
To learn more about the Startin'blox components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
source/import_documentation/what-is-sib.rst → source/import_documentation/first_step/sib-presentation.rst
View file @ 405339e9
What is Startin'blox?
***********************
.. _sib-presentation:
Startin'blox presentation
*************************
What is Startin'blox ?
======================
Synopsis
========
--------
Startin'blox is a set of tools based on `Web Components <https://www.webcomponents.org/>`__ and `Linked Data conventions <https://www.w3.org/standards/semanticweb/data>`__ to create applications compatibles with the `SOLID specifications <https://github.com/solid/solid-spec/>`__.
Those tools are developed by the cooperative of the same name.
We are all, as users, captive to the digital platforms we use, attached to them by the network effect over which they have a monopoly.
Thanks to W3C and `the work of Tim Berners-Lee <https://solid.mit.edu/>`__, an alternative is possible. The new web standards allow the network effect to be shared between the different digital tools and give us back total control over our personal data.
Thanks to W3C and `the work of Tim Berners-Lee <https://solid.mit.edu/>`__, an alternative is possible.
The new web standards allow the network effect to be shared between the different digital tools and give us back total control over our personal data.
**Startin'blox has set itself the mission of precipitating the advent of this new type of digital platform.**
We've built a solution to make the creation of federated and interoperable applications as accessible as possible.
.. figure:: ../_static/images/import_documentation/federation.png
.. figure:: ../../_static/images/import_documentation/federation.png
:alt: Federation concept
=> To know more about Startin'blox, have a look to `our website <https://startinblox.com/>`__.
Explanation
===========
-----------
Global overview
---------------
~~~~~~~~~~~~~~~
Startin'blox is composed of:
A front framework
..................
**Startin'blox mainly develops a solution for creating web applications based on front-end development.**
It can be imported by a simple script in a html file and provides you basics functionalities like making a form, displaying data, a map, a calendar etc..
To learn more about the framework components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
In the Startin'blox philosophy, the logic of the data processing is done on the front side.
In the Startin'blox philosophy, the logic of the data processing is done on the front side.
Extended features components
............................
Components are web components that correspond to functionalities that you can easily add to existing applications. Startin'blox creates components according to its uses but in the future we encourage the development of community components.
Components are web components that correspond to functionalities that you can easily add to existing applications.
Startin'blox creates components according to its uses but in the future we encourage the development of community components.
For example, Sib-Directory provides you with a user directory that includes user skills.
.. figure:: ../_static/images/import_documentation/Components.png
.. figure:: ../../_static/images/import_documentation/Components.png
:alt: Component example
Each component treats a specific shape of data. The validation of this shape is made on the server side.
A server solution
.................
We offer a server solution based on the `Django framework <https://www.djangoproject.com/>`__ and adapted to be compatible with the Linked datas platform conventions, named DjangoLDP.
We offer a server solution based on the `Django framework <https://www.djangoproject.com/>`__ and adapted to be compatible with
the Linked datas platform conventions, named :ref:`DjangoLDP <djangoldp-guide-intro>`.
It is a simple architecture on which we can add LDP packages, corresponding to the different components used. Those are the ones that will do the work of validating the application data.
It is a simple architecture on which we can add LDP packages, corresponding to the different components used.
Those are the ones that will do the work of validating the application data.
.. figure:: ../_static/images/import_documentation/Overview-server.png
.. figure:: ../../_static/images/import_documentation/Overview-server.png
:alt: Server overview
.. note::
......@@ -60,20 +72,77 @@ It is a simple architecture on which we can add LDP packages, corresponding to t
The solution can be summarized as follows:
.. figure:: ../_static/images/import_documentation/Overview-of-SiB.png
.. figure:: ../../_static/images/import_documentation/Overview-of-SiB.png
:alt: SiB overview
Overview of the Framework
--------------------------
.. warning::
The section should be improve
Overview of the Framework
~~~~~~~~~~~~~~~~~~~~~~~~~
Here is a brief presentation:
.. figure:: ../_static/images/import_documentation/Framework-Overview.png
.. figure:: ../../_static/images/import_documentation/Framework-Overview.png
:alt: Framework Overview
`To go deeper <https://git.happy-dev.fr/startinblox/framework/sib-core/>`__.
The framework is composed of **base components** that allow data to be displayed, modified, searched ... These functionalities are defined by attributes, specific to the components themselves or proposed by the framework **mixins**.
Finally, the **store** is responsible for managing the data.
To go deeper in the framework discovery and understanding, go to consult :ref:`framework guide introduction <framework-guide-intro>`, or take a look at `source code <https://git.startinblox.com/framework/sib-core>`__.
Follow the :ref:`Startin'blox podcast tutorial <podcast-tutorial>` offers a step-by-step introduction to the framework.
Why use Startin'blox ?
======================
Fast and Easy
-------------
Startin’blox technology is aimed at enabling **anyone with little
development skills** to create their own web application easily and
quicky respecting both the `web components
standards <https://developer.mozilla.org/fr/docs/Web/Web_Components>`__
and the `Linked Data Platform
convention <https://en.wikipedia.org/wiki/Linked_Data_Platform>`__.
Moreover, it allows today to connect communities and make federated applcation.
Effortlessly, you can compose your app with ready-made HTML components, each of which provides an entire feature.
Add HTML tags with the right attributes and watch your application build itself.
Decentralized
-------------
Today’s applications have their own database. A back depends on a front
and screw and vice versa. In a decentralized web, there are data sources
and client applications that use these datas.
This is made possible by the fact that **the data
is** `interoperable <https://en.wikipedia.org/wiki/Interoperability>`__
because it is written in `RDF <https://www.w3.org/RDF/>`__, the basic
language of the `semantic
web <https://en.wikipedia.org/wiki/Semantic_Web>`__.
Starin’blox is a front-end framework composed of `web
components <https://en.wikipedia.org/wiki/Web_Components>`__ that can
receive federated data sources in RDF. This means that you can only use
a component using data sources already available on the web.
.. figure:: ../../_static/images/import_documentation/federation.png
:alt: Federation
Startin’Blox is designed to interconnect applications and their users. Our components can plug into an unlimited number of data sources, so your application connects you to the ecosystem of your choice.
Our work is based on an international project: `The Solid
Project <https://solid.mit.edu/>`__.
Natively modular
----------------
Startin'blox was designed to be modular. It uses the latest standards of linked data and web components. Most modern browsers support them without even a polyfill. You can integrate only one component to an existing application or build an entire application in SiB.
.. note::
We should add more draw and uses cases. It's the theory page.
\ No newline at end of file