mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-04-26 05:58:27 -05:00
update pathes to monorepo. init development and depolyment section.
This commit is contained in:
felixboehm
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Development"
|
||||
date: 2020-10-01T20:35:00+01:00
|
||||
weight: -12
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: _index.md
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Deployments Scenarios and Examples
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Building the documentation"
|
||||
date: 2020-07-27T08:39:38+00:00
|
||||
weight: 99
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: building-docs.md
|
||||
---
|
||||
|
||||
## Buildling the documentation
|
||||
|
||||
Following steps can be applied for every oCIS extension repository.
|
||||
|
||||
### Setting up
|
||||
|
||||
- Install [hugo](https://gohugo.io/getting-started/installing/)
|
||||
- Run `make docs`
|
||||
|
||||
### Viewing the documentation
|
||||
|
||||
To view the rendered docs in the browser run:
|
||||
```bash
|
||||
cd hugo
|
||||
hugo -D server
|
||||
```
|
||||
|
||||
Then open "http://localhost:1313/"
|
||||
|
||||
When making changes to the docs, run `make docs` again and the server will pick up the changes and reload the page automatically
|
||||
|
||||
### Deploying the documentation
|
||||
|
||||
The documentation is automatically deployed from the master branch to https://owncloud.github.io/phoenix/
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: "Building"
|
||||
date: 2020-02-27T20:35:00+01:00
|
||||
weight: 30
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: building.md
|
||||
---
|
||||
|
||||
## Build requirements
|
||||
|
||||
All required tools besides `go` and `make` are bundled or getting automatically installed within the `GOPATH`. All commands to build this project are part of our `Makefile`.
|
||||
|
||||
The installation of Go is out of the scope of this document, please follow the official documentation for [Go](https://golang.org/doc/install), to build this project you have to install Go >= v1.13.
|
||||
|
||||
## Get the sources
|
||||
|
||||
{{< highlight txt >}}
|
||||
git clone https://github.com/owncloud/ocis.git
|
||||
cd ocis
|
||||
{{< / highlight >}}
|
||||
|
||||
# Build the `ocis` binary
|
||||
|
||||
The ocis binary source is in the ocis/ocis folder. In this folder you can build the ocis binary:
|
||||
|
||||
{{< highlight txt >}}
|
||||
make generate
|
||||
make build
|
||||
{{< / highlight >}}
|
||||
|
||||
Finally, you should have the binary within the `bin/` folder now, give it a try with `./bin/ocis -h` to see all available options.
|
||||
|
||||
## Build a local ocis docker image
|
||||
|
||||
If you are developing on a local branch based on docker / docker-compose setup, here is how to build a new ocis image. In the root folder:
|
||||
|
||||
{{< highlight txt >}}
|
||||
docker build -t owncloud/ocis:local .
|
||||
{{< / highlight >}}
|
||||
|
||||
Then you can test as usual via
|
||||
|
||||
{{< highlight txt >}}
|
||||
docker run --rm -ti owncloud/ocis:dev
|
||||
{{< / highlight >}}
|
||||
@@ -0,0 +1,217 @@
|
||||
---
|
||||
title: "Debugging"
|
||||
date: 2020-03-19T08:21:00+01:00
|
||||
weight: 50
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: debugging.md
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
As a single binary for easy deployment running `ocis server` just forks itself to start all the services, which makes debugging those processes a little harder.
|
||||
|
||||
Ultimately, we want to be able to stop a single service using eg. `ocis kill phoenix` so that you can start the service you want to debug in debug mode. We need to [change the way we fork processes](https://github.com/owncloud/ocis/issues/77) though, otherwise the runtime will automatically restart a service if killed.
|
||||
|
||||
### Start ocis
|
||||
|
||||
For debugging there are two workflows that work well, depending on your preferences.
|
||||
|
||||
#### Use the debug binary and attach to the process as needed
|
||||
|
||||
Run the debug binary with `OCIS_LOG_LEVEL=debug bin/ocis-debug server` and then find the service you want to debug using:
|
||||
|
||||
```console
|
||||
# ps ax | grep ocis
|
||||
12837 pts/1 Sl+ 0:00 bin/ocis-debug server
|
||||
12845 pts/1 Sl 0:00 bin/ocis-debug graph
|
||||
12847 pts/1 Sl 0:00 bin/ocis-debug reva-auth-bearer
|
||||
12848 pts/1 Sl 0:00 bin/ocis-debug graph-explorer
|
||||
12849 pts/1 Sl 0:00 bin/ocis-debug ocs
|
||||
12850 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc-data
|
||||
12863 pts/1 Sl 0:00 bin/ocis-debug webdav
|
||||
12874 pts/1 Sl 0:00 bin/ocis-debug reva-frontend
|
||||
12897 pts/1 Sl 0:00 bin/ocis-debug reva-sharing
|
||||
12905 pts/1 Sl 0:00 bin/ocis-debug reva-gateway
|
||||
12912 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home
|
||||
12920 pts/1 Sl 0:00 bin/ocis-debug reva-users
|
||||
12929 pts/1 Sl 0:00 bin/ocis-debug glauth
|
||||
12940 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home-data
|
||||
12948 pts/1 Sl 0:00 bin/ocis-debug konnectd
|
||||
12952 pts/1 Sl 0:00 bin/ocis-debug proxy
|
||||
12961 pts/1 Sl 0:00 bin/ocis-debug thumbnails
|
||||
12971 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc
|
||||
12981 pts/1 Sl 0:00 bin/ocis-debug web
|
||||
12993 pts/1 Sl 0:00 bin/ocis-debug api
|
||||
12998 pts/1 Sl 0:00 bin/ocis-debug registry
|
||||
13004 pts/1 Sl 0:00 bin/ocis-debug phoenix
|
||||
13015 pts/1 Sl 0:00 bin/ocis-debug reva-auth-basic
|
||||
```
|
||||
|
||||
Then you can set a breakpoint in the service you need and attach to the process via processid. To debug the `reva-sharing` service the VS Code `launch.json` would look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "ocis attach",
|
||||
"type": "go",
|
||||
"request": "attach",
|
||||
"mode": "local",
|
||||
"processId": 12897,
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Start all services independently to replace one of them with a debug process
|
||||
|
||||
1. You can use this `./ocis.sh` script to start all services independently, so they don't get restrarted by the runtime when you kill them:
|
||||
```bash
|
||||
#/bin/sh
|
||||
LOG_LEVEL="debug"
|
||||
|
||||
bin/ocis --log-level=$LOG_LEVEL micro &
|
||||
|
||||
bin/ocis --log-level=$LOG_LEVEL glauth &
|
||||
bin/ocis --log-level=$LOG_LEVEL graph-explorer &
|
||||
bin/ocis --log-level=$LOG_LEVEL graph &
|
||||
#bin/ocis --log-level=$LOG_LEVEL hello &
|
||||
bin/ocis --log-level=$LOG_LEVEL konnectd &
|
||||
#bin/ocis --log-level=$LOG_LEVEL ocs &
|
||||
bin/ocis --log-level=$LOG_LEVEL phoenix &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-auth-basic &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-auth-bearer &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-frontend &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-gateway &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-sharing &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-storage-home &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-storage-home-data &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-storage-oc &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-storage-oc-data &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-storage-root &
|
||||
bin/ocis --log-level=$LOG_LEVEL reva-users &
|
||||
#bin/ocis --log-level=$LOG_LEVEL webdav
|
||||
|
||||
bin/ocis --log-level=$LOG_LEVEL proxy &
|
||||
```
|
||||
|
||||
2. Get the list of running processes:
|
||||
|
||||
```console
|
||||
# ps ax | grep ocis
|
||||
12837 pts/1 Sl+ 0:00 bin/ocis-debug server
|
||||
12845 pts/1 Sl 0:00 bin/ocis-debug graph
|
||||
12847 pts/1 Sl 0:00 bin/ocis-debug reva-auth-bearer
|
||||
12848 pts/1 Sl 0:00 bin/ocis-debug graph-explorer
|
||||
12849 pts/1 Sl 0:00 bin/ocis-debug ocs
|
||||
12850 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc-data
|
||||
12863 pts/1 Sl 0:00 bin/ocis-debug webdav
|
||||
12874 pts/1 Sl 0:00 bin/ocis-debug reva-frontend
|
||||
12897 pts/1 Sl 0:00 bin/ocis-debug reva-sharing
|
||||
12905 pts/1 Sl 0:00 bin/ocis-debug reva-gateway
|
||||
12912 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home
|
||||
12920 pts/1 Sl 0:00 bin/ocis-debug reva-users
|
||||
12929 pts/1 Sl 0:00 bin/ocis-debug glauth
|
||||
12940 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home-data
|
||||
12948 pts/1 Sl 0:00 bin/ocis-debug konnectd
|
||||
12952 pts/1 Sl 0:00 bin/ocis-debug proxy
|
||||
12961 pts/1 Sl 0:00 bin/ocis-debug thumbnails
|
||||
12971 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc
|
||||
12981 pts/1 Sl 0:00 bin/ocis-debug web
|
||||
12993 pts/1 Sl 0:00 bin/ocis-debug api
|
||||
12998 pts/1 Sl 0:00 bin/ocis-debug registry
|
||||
13004 pts/1 Sl 0:00 bin/ocis-debug phoenix
|
||||
13015 pts/1 Sl 0:00 bin/ocis-debug reva-auth-basic
|
||||
```
|
||||
|
||||
3. Kill the service you want to start in debug mode:
|
||||
|
||||
|
||||
```console
|
||||
# kill 17628
|
||||
```
|
||||
|
||||
4. Start the service you are interested in in debug mode. When using make to build the binary there is already a `bin/ocis-debug` binary for you. When running an IDE tell it which service to start by providing the corresponding sub command, eg. `bin\ocis-debug reva-frontend`.
|
||||
|
||||
### Gather error messages
|
||||
|
||||
We recommend you collect all related information in a single file or in a github issue. Let us start with an error that pops up in the Web UI:
|
||||
|
||||
> Error while sharing.
|
||||
> error sending a grpc stat request
|
||||
|
||||
This popped up when I tried to add `marie` as a collaborator in phoenix. That triggers a request to the server which I copied as curl. We can strip a lot of headers and the gist of it is:
|
||||
|
||||
```console
|
||||
# curl 'https://localhost:9200/ocs/v1.php/apps/files_sharing/api/v1/shares' -d 'shareType=0&shareWith=marie&path=%2FNeuer+Ordner&permissions=1' -u einstein:relativity -k -v | xmllint -format -
|
||||
[... headers ...]
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>error</status>
|
||||
<statuscode>998</statuscode>
|
||||
<message>error sending a grpc stat request</message>
|
||||
</meta>
|
||||
</ocs>
|
||||
```
|
||||
|
||||
{{< hint info >}}
|
||||
The username and password only work when basic auth is available. Otherwise you have to obtain a bearer token, eg. by grabbing it from the browser.
|
||||
{{< /hint >}}
|
||||
{{< hint danger >}}
|
||||
TODO add ocis cli tool to obtain a bearer token.
|
||||
{{< /hint >}}
|
||||
|
||||
We also have a few interesting log entries:
|
||||
|
||||
```
|
||||
0:43PM INF home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/grpc/interceptors/log/log.go:69 > unary code=OK end="18/Mar/2020:22:43:40 +0100" from=tcp://[::1]:44078 pid=17836 pkg=rgrpc start="18/Mar/2020:22:43:40 +0100" time_ns=95841 traceid=b4eb9a9f45921f7d3632523ca32a42b0 uri=/cs3.storage.registry.v1beta1.RegistryAPI/GetStorageProvider user-agent=grpc-go/1.26.0
|
||||
10:43PM ERR home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/grpc/interceptors/log/log.go:69 > unary code=Unknown end="18/Mar/2020:22:43:40 +0100" from=tcp://[::1]:43910 pid=17836 pkg=rgrpc start="18/Mar/2020:22:43:40 +0100" time_ns=586115 traceid=b4eb9a9f45921f7d3632523ca32a42b0 uri=/cs3.gateway.v1beta1.GatewayAPI/Stat user-agent=grpc-go/1.26.0
|
||||
10:43PM ERR home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/http/services/owncloud/ocs/reqres.go:94 > error sending a grpc stat request error="rpc error: code = Unknown desc = gateway: error calling Stat: rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp [::1]:9152: connect: connection refused\"" pid=17832 pkg=rhttp traceid=b4eb9a9f45921f7d3632523ca32a42b0
|
||||
```
|
||||
|
||||
{{< hint danger >}}
|
||||
TODO return the trace id in the response so we can correlate easier. For reva tracked in https://github.com/cs3org/reva/issues/587
|
||||
{{< /hint >}}
|
||||
|
||||
The last line gives us a hint where the log message originated: `.../github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/http/services/owncloud/ocs/reqres.go:94`. Which looks like this:
|
||||
|
||||
```go
|
||||
89: // WriteOCSResponse handles writing ocs responses in json and xml
|
||||
90: func WriteOCSResponse(w http.ResponseWriter, r *http.Request, res *Response, err error) {
|
||||
91: var encoded []byte
|
||||
92:
|
||||
93: if err != nil {
|
||||
94: appctx.GetLogger(r.Context()).Error().Err(err).Msg(res.OCS.Meta.Message)
|
||||
95: }
|
||||
```
|
||||
|
||||
Ok, so this seems to be a convenience method that is called from multiple places an also handles errors. Unfortunately, this hides the actual source of the error. We could set a breakpoint in line 94 and reproduce the problem, which can be a lot harder than just clicking the share button or sending a curl request again. So let us see what else the log tells us.
|
||||
|
||||
The previous line tells us that a Stat request failed: `uri=/cs3.gateway.v1beta1.GatewayAPI/Stat`. This time the line is written by the grpc log interceptor. What else is there?
|
||||
|
||||
The first line tells us that looking up the responsible storage provider seems to have succeeded: `uri=/cs3.storage.registry.v1beta1.RegistryAPI/GetStorageProvider`.
|
||||
|
||||
At this point it your familiarity with the codebase starts to become a factor. If you are new you should probably go back to setting a break point on the log line and check the stack trace.
|
||||
|
||||
Debug wherever the call trace leads you to ... good luck!
|
||||
|
||||
### Managing dependencies and testing changes
|
||||
|
||||
You can either run and manage the services independently, or you can update the `go.mod` file and replace dependencies with your local version.
|
||||
|
||||
To debug the reva frontend we need to add two replacements:
|
||||
```
|
||||
// use the local ocis-reva repo
|
||||
replace github.com/owncloud/ocis-reva => ../ocis-reva
|
||||
// also use the local reva repo
|
||||
replace github.com/cs3org/reva => ../reva
|
||||
```
|
||||
{{< hint info >}}
|
||||
The username and password only work when basic auth is available. Otherwise you have to obtain a bearer token, eg. by grabbing it from the browser.
|
||||
{{< /hint >}}
|
||||
|
||||
Rebuild ocis to make sure the dependency is used. It should be sufficient to just restart the service you want to debug.
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: "Getting Started with Development"
|
||||
date: 2020-07-07T20:35:00+01:00
|
||||
weight: 15
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: getting-started.md
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Docker dev environment
|
||||
|
||||
### Option 1: Plain docker
|
||||
|
||||
To build and run your local ocis code with default storage driver
|
||||
|
||||
```
|
||||
docker run --rm -ti --name ocis -v $PWD:/ocis -p 9200:9200 owncloud/eos-ocis-dev
|
||||
```
|
||||
|
||||
The eos-ocis-dev container will build and run ocis using the owncloud storage driver and store files in the container at `/var/tmp/reva/data/<username>/files`
|
||||
|
||||
To check the uploaded files start digging with: `docker exec -it ocis ls -l /var/tmp/reva/`
|
||||
|
||||
{{< hint info >}}
|
||||
On MacOS do not mount a local folder to the `/var/tmp/reva/` path. The fuse driver used by docker [does not support extended attributes](https://docs.docker.com/v18.09/docker-for-mac/osxfs/). See [#182](https://github.com/owncloud/ocis/issues/182) for more details.
|
||||
{{< /hint >}}
|
||||
|
||||
|
||||
### Option 2: Docker compose
|
||||
|
||||
With the `docker-compose.yml` file in ocis repo you can also start ocis via compose:
|
||||
|
||||
```
|
||||
docker-compose up -d ocis
|
||||
```
|
||||
|
||||
{{< hint info >}}
|
||||
We are only starting the `ocis` container here.
|
||||
{{< /hint >}}
|
||||
|
||||
## Verification
|
||||
|
||||
Check the services are running
|
||||
|
||||
```
|
||||
$ docker-compose exec ocis ./bin/ocis list
|
||||
+--------------------------+-----+
|
||||
| EXTENSION | PID |
|
||||
+--------------------------+-----+
|
||||
| accounts | 172 |
|
||||
| api | 204 |
|
||||
| glauth | 187 |
|
||||
| graph | 41 |
|
||||
| graph-explorer | 55 |
|
||||
| konnectd | 196 |
|
||||
| ocs | 59 |
|
||||
| phoenix | 29 |
|
||||
| proxy | 22 |
|
||||
| registry | 226 |
|
||||
| reva-auth-basic | 96 |
|
||||
| reva-auth-bearer | 104 |
|
||||
| reva-frontend | 485 |
|
||||
| reva-gateway | 78 |
|
||||
| reva-sharing | 286 |
|
||||
| reva-storage-eos | 129 |
|
||||
| reva-storage-eos-data | 134 |
|
||||
| reva-storage-home | 442 |
|
||||
| reva-storage-home-data | 464 |
|
||||
| reva-storage-oc | 149 |
|
||||
| reva-storage-oc-data | 155 |
|
||||
| reva-storage-public-link | 168 |
|
||||
| reva-users | 420 |
|
||||
| settings | 23 |
|
||||
| thumbnails | 201 |
|
||||
| web | 218 |
|
||||
| webdav | 63 |
|
||||
+--------------------------+-----+
|
||||
```
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: "Testing"
|
||||
date: 2018-05-02T00:00:00+00:00
|
||||
weight: 37
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: testing.md
|
||||
---
|
||||
|
||||
|
||||
## Acceptance tests
|
||||
|
||||
We are using the ownCloud 10 acceptance testsuite against ocis. To set this up you need the owncloud 10 core repo, a ldap server that the acceptance tests can use to manage users, a redis server for file-versions and the ocis code.
|
||||
|
||||
### Getting the tests
|
||||
|
||||
All you need to do to get the acceptance tests is check out the core repo:
|
||||
```
|
||||
git clone https://github.com/owncloud/core.git
|
||||
```
|
||||
|
||||
### Run a redis server in a docker container
|
||||
|
||||
File versions need a redis server. Start one with docker by using:
|
||||
|
||||
`docker run -e REDIS_DATABASES=1 -p 6379:6379 -d webhippie/redis:latest`
|
||||
|
||||
### Run ocis
|
||||
|
||||
To start ocis:
|
||||
```
|
||||
bin/ocis server
|
||||
```
|
||||
|
||||
### Run the acceptance tests
|
||||
First we will need to clone the testing app in owncloud which contains the skeleton files required for running the tests.
|
||||
In the ownCloud 10 core clone the testing app with the following command:
|
||||
|
||||
```
|
||||
git clone https://github.com/owncloud/testing apps/testing
|
||||
```
|
||||
|
||||
Then run the api acceptance tests with the following command:
|
||||
```
|
||||
make test-acceptance-api \
|
||||
TEST_SERVER_URL=https://localhost:9200 \
|
||||
TEST_OCIS=true \
|
||||
OCIS_REVA_DATA_ROOT=/var/tmp/reva/ \
|
||||
SKELETON_DIR=apps/testing/data/apiSkeleton \
|
||||
BEHAT_FILTER_TAGS='~@notToImplementOnOCIS&&~@toImplementOnOCIS'
|
||||
```
|
||||
|
||||
Make sure to adjust the settings `TEST_SERVER_URL` and `OCIS_REVA_DATA_ROOT` according to your environment.
|
||||
|
||||
This will run all tests that are relevant to OCIS.
|
||||
|
||||
To run a single test add `BEHAT_FEATURE=<feature file>`
|
||||
|
||||
### use existing tests for BDD
|
||||
|
||||
As a lot of scenarios are written for oC10, we can use those tests for Behaviour driven development in ocis.
|
||||
Every scenario that does not work in OCIS with OC storage, is listed in `tests/acceptance/expected-failures-on-OC-storage.txt` with a link to the related issue.
|
||||
|
||||
Those scenarios are run in the ordinary acceptance test pipeline in CI. The scenarios that fail are checked against the
|
||||
expected failures. If there are any differences then the CI pipeline fails.
|
||||
Similarly, scenarios that do not work in OCIS with EOS storage are listed in `tests/acceptance/expected-failures-on-EOS-storage.txt`.
|
||||
Additionally, some issues have scenarios that demonstrate the current buggy behaviour in ocis(reva).
|
||||
Those scenarios are in this ocis repository in `tests/acceptance/features/apiOcisSpecific`.
|
||||
Have a look into the [documentation](https://doc.owncloud.com/server/developer_manual/testing/acceptance-tests.html#writing-scenarios-for-bugs) to understand why we are writing those tests.
|
||||
|
||||
If you want to work on a specific issue
|
||||
|
||||
1. adjust the core commit id to the latest commit in core so that CI will run the latest test code and scenarios from core.
|
||||
For that change `coreCommit` in the `config` section:
|
||||
|
||||
config = {
|
||||
'apiTests': {
|
||||
'coreBranch': 'master',
|
||||
'coreCommit': 'a06b1bd5ba8e5244bfaf7fa04f441961e6fb0daa',
|
||||
'numberOfParts': 2
|
||||
}
|
||||
}
|
||||
|
||||
2. locally run each of the tests marked with that issue in the expected failures file
|
||||
|
||||
E.g.:
|
||||
```
|
||||
make test-acceptance-api \
|
||||
TEST_SERVER_URL=https://localhost:9200 \
|
||||
TEST_OCIS=true \
|
||||
OCIS_REVA_DATA_ROOT=/var/tmp/reva/ \
|
||||
BEHAT_FEATURE='tests/acceptance/features/apiComments/comments.feature:123'
|
||||
```
|
||||
|
||||
3. the tests will fail, try to understand how and why they are failing
|
||||
4. fix the code
|
||||
5. go back to 2. and repeat till the tests are passing.
|
||||
6. remove those tests from the expected failures file
|
||||
7. run each of the local tests that were demonstrating the **buggy** behavior. They should fail.
|
||||
8. delete each of the local tests that were demonstrating the **buggy** behavior.
|
||||
9. make a PR that has the fixed code, relevant lines removed from the expected failures file and bug demonstration tests deleted.
|
||||
|
||||
If the changes also affect the `ocis-reva` repository make sure the changes get ported over there.
|
||||
|
||||
### Notes
|
||||
- in a normal case the test-code cleans up users after the test-run, but if a test-run is interrupted (e.g. by CTRL+C) users might have been left on the LDAP server. In that case rerunning the tests requires wiping the users in the ldap server, otherwise the tests will fail when trying to populate the users.
|
||||
- the tests usually create users in the OU `TestUsers` with usernames specified in the feature file. If not defined in the feature file, most users have the password `123456`, defined by `regularUserPassword` in `behat.yml`, but other passwords are also used, see [`\FeatureContext::getPasswordForUser()`](https://github.com/owncloud/core/blob/master/tests/acceptance/features/bootstrap/FeatureContext.php#L386) for mapping and [`\FeatureContext::__construct`](https://github.com/owncloud/core/blob/master/tests/acceptance/features/bootstrap/FeatureContext.php#L1668) for the password definitions.
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Tracing"
|
||||
date: 2020-05-13T12:09:00+01:00
|
||||
weight: 55
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/development
|
||||
geekdocFilePath: tracing.md
|
||||
---
|
||||
|
||||
By default, we use [Jaeger](https://www.jaegertracing.io) for request tracing within oCIS. You can follow these steps
|
||||
to get started:
|
||||
|
||||
1. Start Jaeger by using the all-in-one docker image:
|
||||
```console
|
||||
docker run -d --name jaeger \
|
||||
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
|
||||
-p 5775:5775/udp \
|
||||
-p 6831:6831/udp \
|
||||
-p 6832:6832/udp \
|
||||
-p 5778:5778 \
|
||||
-p 16686:16686 \
|
||||
-p 14268:14268 \
|
||||
-p 14250:14250 \
|
||||
-p 9411:9411 \
|
||||
jaegertracing/all-in-one:1.17
|
||||
```
|
||||
2. Every single oCIS service has its own environment variables for enabling and configuring tracing.
|
||||
1. You can enable and configure tracing on each service individually. For example, enable tracing
|
||||
in Reva when starting the oCIS single binary like this:
|
||||
```console
|
||||
REVA_TRACING_ENABLED=true \
|
||||
REVA_TRACING_ENDPOINT=localhost:6831 \
|
||||
REVA_TRACING_COLLECTOR=http://localhost:14268/api/traces \
|
||||
./bin/ocis server
|
||||
```
|
||||
2. Enabling and configuring tracing on oCIS itself will forward the configuration to all services:
|
||||
```console
|
||||
OCIS_TRACING_ENABLED=true \
|
||||
OCIS_TRACING_ENDPOINT=localhost:6831 \
|
||||
OCIS_TRACING_COLLECTOR=http://localhost:14268/api/traces \
|
||||
./bin/ocis server
|
||||
```
|
||||
If you want to set individual tracing configuration for each service, make sure to set
|
||||
`OCIS_TRACING_ENABLED=false`.
|
||||
3. Make the actual request that you want to trace.
|
||||
4. Open up the [Jaeger UI](http://localhost:16686) to analyze request traces.
|
||||
|
||||
For more information on Jaeger, please refer to their [Documentation](https://www.jaegertracing.io/docs/1.17/).
|
||||
Reference in New Issue
Block a user