A client for your Portus instance
Switch branches/tags
Nothing to show
Clone or download
mssola Merge pull request #17 from openSUSE/different-go-versions
Pinning down the exact Go versions supported
Latest commit d9e84f9 Oct 11, 2018
Permalink
Failed to load latest commit information.
.github Added badges and github templates Feb 23, 2018
Godeps Improved the lookup of resources Nov 15, 2017
contrib/pkg/suse contrib/pkg/suse: fixed md2man package name Jan 26, 2018
man Implemented bootstrap command Sep 28, 2018
test Implemented bootstrap command Sep 28, 2018
vendor Updated license notice Jan 2, 2018
.gitignore Added code coverage report Nov 29, 2017
.travis.yml Pinning down the exact Go versions supported Oct 11, 2018
CHANGELOG.md Initial commit Oct 27, 2017
CONTRIBUTING.md Added code coverage report Nov 29, 2017
COPYING Initial commit Oct 27, 2017
Makefile packaging: do not require moreutils or git Jan 26, 2018
README.md Pinning down the exact Go versions supported Oct 11, 2018
VERSION Added integration tests Nov 14, 2017
bootstrap.go Implemented bootstrap command Sep 28, 2018
cli.go Implemented bootstrap command Sep 28, 2018
cli_test.go Implemented explain command Sep 20, 2018
entities.go Fixed integration tests Sep 26, 2018
entities_test.go Updated license notice Jan 2, 2018
exec.go exec: simplified the way to fetch the ruby version Jan 26, 2018
explain.go Implemented explain command Sep 20, 2018
explain_test.go Implemented explain command Sep 20, 2018
health.go Implemented bootstrap command Sep 28, 2018
http.go Implemented bootstrap command Sep 28, 2018
portusctl.go Implemented bootstrap command Sep 28, 2018
portusctl_test.go test: fixed bundle calls and removed dependencies Jan 26, 2018
printer.go Implemented bootstrap command Sep 28, 2018
resource.go Implemented bootstrap command Sep 28, 2018
resource_test.go Updated license notice Jan 2, 2018
utils.go Updated license notice Jan 2, 2018
utils_test.go Updated license notice Jan 2, 2018
version.go Implemented bootstrap command Sep 28, 2018

README.md

portusctl Build Status Go Report Card

portusctl is a client for your Portus instance. It allows you to access the REST API offered by Portus and present the results in a friendly manner. For example:

$ portusctl get users
...(output)...
ID    Username    Email                Admin    NamespaceID    DisplayName
1     portus      portus@portus.com    true     2
2     mssola      admin@portus.test    true     3

$ portusctl get -f json users 2 | jq
...(output)...
{
    "id": 2,
    "username": "mssola",
    "email": "admin@portus.test",
    "current_sign_in_at": "2017-11-22T14:30:52.000Z",
    "last_sign_in_at": "2017-11-16T09:23:34.000Z",
    "created_at": "2017-11-14T14:22:01.000Z",
    "updated_at": "2017-11-22T14:30:52.000Z",
    "admin": true,
    "enabled": true,
    "locked_at": null,
    "namespace_id": 3,
    "display_name": ""
}

$ portusctl create user username=user email=user@portus.test password=12341234
...(output)...
ID    Username    Email               Admin    NamespaceID    DisplayName
3     user        user@portus.test    false    5

$ portusctl update user 3 display_name=User
...(output)...
ID    Username    Email               Admin    NamespaceID    DisplayName
3     user        user@portus.test    false    5              User

Moreover, it also allows you to execute arbitrary commands on the Portus' context if your instance is running locally:

$ portusctl exec cat .ruby-version
2.4.2

portusctl does not implement all the API entrypoints available as of Portus v2.4. You can follow the progress of this here. The exec command is considered stable already, and that's why portusctl is included inside of the Portus Docker image as of v2.4.

Note well: portusctl is targetting the API from the Portus' master branch, which is still under heavy development. Hence, we recommend using both the latest portusctl together with the latest commit of Portus. This situation will change once the API starts to stabilize.

Installation

You can install portusctl from source by cloning this repository and then performing the following command:

$ make install

You can also install portusctl from obs://Virtualization:containers:Portus. In order to install it with zypper you need to perform the following commands:

% zypper ar -f https://download.opensuse.org/repositories/Virtualization:/containers:/Portus/openSUSE_Leap_42.3/ portus
% zypper install portusctl

It is required at least Go 1.8.x in order to install portusctl.

Development

You could build this project as any other Go binary with go build, but this is not recommended. Instead, use the default make target:

$ make
# or the equivalent `make portusctl`

With this command, portusctl will be built with the desired build flags and setting the proper version for it. Note that the build can be further customized with the BUILD_FLAGS variable. So, you could pass extra arguments like so:

$ make BUILD_FLAGS="-v"

When doing this you should be careful to not conflict with a default build flag.

Unit testing

Unit testing is performed through the test-unit make target:

$ make test-unit

Integration testing

We use bats for integration testing and docker-compose. There is a specific target on the Makefile called test-integration, which will run the test integration suite:

$ make test-integration

This will setup a Portus instance running in the background as a Docker container (through docker-compose), and then it will run the tests targeting this Portus instance.

There are some nice flags when running integration tests:

  • SKIP_ENV_TESTS: when set to true, it will skip the process of bringing your Portus instance up. You should use this flag when you want to re-use a previous environment for your tests (bear in mind that between each test case the database will be cleaned up). It is set to false by default.
  • TEARDOWN_TESTS: when set to true, it will destroy the Portus instance at the end. It is set to true by default.
  • TESTS: you can define a list of tests to be run. This way you can specify that you want to run only a specific subset of tests instead of the whole suite.

Taken that into account, you should perform the following when running tests for the first time:

$ make test-integration TEARDOWN_TESTS=

This way you will have the Portus instance available and it won't be destroyed at the end. Then, for successive runs you can perform:

$ make test-integration SKIP_ENV_TESTS=1 TEARDOWN_TESTS=

If only you care about a specific test (e.g. the test/users.bats file):

$ make test-integration TESTS=users SKIP_ENV_TESTS=1 TEARDOWN_TESTS=

Validation

Besides running tests, we also perform some validation tests on the code. These tests can be run like this:

$ make validate

Man pages

Man pages have been written using Markdown, and they can be found in the man directory. In order to generate man pages from these markdown files, you have to run the following command:

$ make doc

Code coverage

If you want to perform both unit and integration testing, then you can simply call the test target like this:

$ make test

This target has one extra benefit: it will also check for code coverage. If code coverage is below an expected threshold, then you will get a report about it.

Note though that you need the sponge command installed on your system.

What the CI will end up running

The CI will only run the ci target, which will in turn:

  1. Run all validators.
  2. Run unit & integration tests.
  3. Perform checks on code coverage.

It is recommended that you perform make ci before submitting a pull request, and check that it ran successfully.

License

This project is based on work we did for the Portus project. However, all the code has been re-written from scratch, so the entire project is subject to the GPLv3 license:

Copyright (C) 2017-2018 Miquel Sabaté Solà <msabate@suse.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.