Skip to content

Commit 3854755

Browse files
ylebreylebre
authored
Merge pull request #147 from pdsinterop/docs/depoy
Change deploy / publish instruction to live in a separate file.
2 parents 42374e2 + 22b4711 commit 3854755

2 files changed

Lines changed: 134 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -29,32 +29,6 @@ There is a [GitHub Action](https://github.com/pdsinterop/solid-nextcloud/actions
2929
## Manual testing
3030
You can try out the various Solid apps that show up in the Solid App GUI inside the Nextcloud GUI on first use.
3131

32-
# Publishing to the Nextcloud app store
32+
### Build / Deploy
3333

34-
* `git checkout main`
35-
* `git pull`
36-
* Tag v0.0.X in solid/appinfo/info.xml
37-
* `git tag`
38-
* `git tag v0.0.X`
39-
* `git push --follow-tags`
40-
* `git checkout publish`
41-
* `git pull`
42-
* `git merge main`
43-
* `cd solid`
44-
* `php ../composer.phar update`
45-
* `php ../composer.phar install --no-dev --prefer-dist`
46-
* `git commit -am"built"` (at least `vendor/composer/installed.php` will have changed)
47-
* `git push`
48-
* `cd ..`
49-
* create a release on github from the tag you just pushed
50-
* `tar -cf solid.tar solid/`
51-
* `gzip solid.tar`
52-
* `git checkout main`
53-
* edit the release and upload `solid.tar.gz` as a binary attachment
54-
* make sure transfer/solid.key and transfer/solid.crt exist
55-
* `openssl dgst -sha512 -sign ./transfer/solid.key ./solid.tar.gz | openssl base64`
56-
* visit https://apps.nextcloud.com/developer/apps/releases/new
57-
* go into the developer tools browser console to change the `<a>` element around the form to a `<p>` element. This makes it possible to fill in values in this form without being redirected.
58-
* fill in for instance `https://github.com/pdsinterop/solid-nextcloud/releases/download/v0.0.2/solid.tar.gz` and the base64 signature from the openssl command
59-
* click 'uploaden'
60-
* good luck!
34+
For publishing to the Nextcloud app store see [the deploy instructions](docs/deploy.md).

‎docs/deploy.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Deploy Process
2+
3+
<!-- toc -->
4+
5+
- [Overview](#overview)
6+
- [Releasing a version](#releasing-a-version)
7+
- [Opening an MR](#opening-an-mr)
8+
- [Tagging a release](#tagging-a-release)
9+
- [Building a package](#building-a-package)
10+
- [Installing dependencies](#installing-dependencies)
11+
- [Creating a tarball](#creating-a-tarball)
12+
- [Deploying the package](#deploying-the-package)
13+
- [Uploading the tarball](#uploading-the-tarball)
14+
- [Creating a release in the Nextcloud App store](#creating-a-release-in-the-nextcloud-app-store)
15+
- [Creating a signature](#creating-a-signature)
16+
- [Adding the signature and link to the Nextcloud App store](#adding-the-signature-and-link-to-the-nextcloud-app-store)
17+
18+
<!-- tocstop -->
19+
20+
## Overview
21+
22+
A _"**release**"_ in the Nextcloud App store consists of a URL where an archive lives (zip, tar, gz, etc.) and a SSL digest (or "signature") with which the integrity of the archive can be validated.
23+
24+
To create a release, both the signature and the URL where the archive can be downloaded need to be posted to the App Store.
25+
The archive is created from the source-code in this repository.
26+
27+
It is a common practice to create a _"**tag**"_, to clearly mark the point in code-base's history where the release has been created.
28+
But the source-code from which the archive is created is not enough _by itself_.
29+
30+
The code also relies on other packages (some of which are created by PDS Interop) in order to function properly.
31+
Because of this, an extra _"**build**"_ step is required between tagging the code and creating the archive.
32+
33+
Thus, to publish a release of this project to the Nextcloud app store, the following steps need to be taken:
34+
35+
- Release a version of the code-base
36+
- Open a release MR
37+
- Tag a release
38+
- Build a package from the tagged release
39+
- Install dependencies
40+
- Create a tarball
41+
- Deploy the built package
42+
- Upload the tarball to the GitHub Release page
43+
- Create a release in the Nextcloud App store
44+
45+
These steps are described in more detail below.
46+
47+
## Releasing a version
48+
49+
A release consists of two things:
50+
51+
- A tag in git, annotated and signed
52+
- A release page on GitHub
53+
54+
The tag is needed so a release page can be created. The release page is needed so there is a place where the tarball can live.
55+
Any changes that need to be made to the code-base for a release should live in a separate branch.
56+
These changes can be merged to the main branch by opening a merge-request (MR).
57+
Once the merge request has been merged, a tag can be created, as well as a release.
58+
59+
### Opening an MR
60+
61+
- Create a `release/v0.X.X` branch
62+
- Change anything that needs to be updated for a new release (at the least the version in `solid/appinfo/info.xml`)
63+
- Open an MR
64+
When the MR is merged a release version can be tagged by creating a GitHub Release
65+
66+
### Tagging a release
67+
68+
It is possible to create a tag locally, using the `git tag` command.
69+
However, this is not needed. When a release is created using the GitHub UI, a tag will be created automatically.
70+
Once that has been done, a package can be built from the release.
71+
72+
## Building a package
73+
74+
The "package" consists of an archived version of the `solid/` directory.
75+
76+
Before a tarball can be created to use as package, various dependencies need to be installed.
77+
78+
### Installing dependencies
79+
80+
Currently, the dependencies this project has are satisfied by composer.
81+
82+
They can be installed using:
83+
84+
```sh
85+
# This command should be run in the `solid/` directory
86+
composer install --no-dev --no-interaction --no-plugins --no-scripts --prefer-dist
87+
```
88+
89+
to make sure the provided dependencies are usable in the supported PHP versions, a docker image can be used.
90+
91+
### Creating a tarball
92+
93+
Once the dependencies are installed, an archive can be created using TAR:
94+
95+
```sh
96+
# This command should be run from the project root
97+
tar --directory="${PWD}" --create --file 'solid.tar.gz' --gzip solid
98+
```
99+
100+
## Deploying the package
101+
102+
After the `solid.tar.gz` tarball has been created, it needs to be uploaded to the GitHub release page.
103+
104+
### Uploading the tarball
105+
106+
The tarball can be uploaded by editing the Release created on GitHub
107+
108+
The tarball URL will be similar to `https://github.com/pdsinterop/solid-nextcloud/releases/download/v0.X.X/solid.tar.gz`
109+
110+
### Creating a release in the Nextcloud App store
111+
112+
#### Creating a signature
113+
114+
Now that the tarball is available at a public URL, the "Upload app release" feature in the Nextcloud App Store can be used to create a release. In order to do so, a "Signature" needs to be created.
115+
116+
⚠ Make sure `transfer/solid.key` and `transfer/solid.crt` exist, as these are both needed to create a signature.
117+
118+
The command to create the signature is:
119+
120+
```
121+
openssl dgst -sha512 -sign ./transfer/solid.key ./solid.tar.gz | openssl base64
122+
```
123+
124+
#### Adding the signature and link to the Nextcloud App store
125+
126+
The signature and URL should be added using the form at https://apps.nextcloud.com/developer/apps/releases/new
127+
128+
Fill in the URL for the tarball from the GitHub release and the base64 signature from the openssl command.
129+
130+
After clicking "upload" a new release _should_ have been created.
131+
132+
This can be verified by visiting the app page in the store: https://apps.nextcloud.com/apps/solid

0 commit comments

Comments
 (0)