summaryrefslogtreecommitdiff
path: root/README.md
blob: a146026f43daa9f956473fc8e4e5f83344cfebfe (about) (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# Hydrilla (Python implementation)

This is the repository of Python incarnation of [Hydrilla](https://hydrillabugs.koszko.org/projects/hydrilla/wiki/Wiki), a repository software to serve [Haketilo](https://hydrillabugs.koszko.org/projects/haketilo/wiki) packages.

## Dependencies

### Runtime

* Python3
* [hydrilla.builder](https://git.koszko.org/hydrilla-builder/)
* flask
* click
* jsonschema

### Build

* setuptools
* wheel
* setuptools_scm
* babel

### Test

* pytest

## Building

We're using setuptools. You can build a wheel under `dist/` with
``` shell
python3 -m build
```
Optionally, add a `--no-isolation` option to the second command to have it use system packages where possible instead of downloading all dependencies from PyPI.

The generated .whl file can then be used to install Hydrilla either globally or in the current Python virtualenv:
```shell
python3 -m pip install dist/put_the_name_of_generated_file_here.whl
```

### PyPI considerations

Commands like `python3 -m build` and `python3 -m pip` but also `virtualenv` will by default download the dependencies from PyPI repository[^pypi]. Although this is what many people want, it carries along a freedom issue. PyPI is not committed to only hosting libre software packages[^pypi_freeware] and, like any platform allowing upload of code by the public, has lower package standards than repositories of many operating system distributions. For this reason you are encouraged to use the dependencies as provided by your distribution.

To perform the build and installation without PyPI, first install all dependencies system-wide. For example, in Debian-based distributions (including Trisquel):
``` shell
sudo apt install python3-flask python3-flask python3-jsonschema \
     python3-setuptools python3-setuptools-scm python3-babel python3-wheel
```

Then, block programs you're about to spawn from accessing https://pypi.org. If running on a GNU/Linux system you can utilize Linux user namespaces:
``` shell
unshare -Urn
```

The above will put you in a network-isolated shell. If you're using a virtualenv, activate it **after** the `unshare` command.

Now, in unpacked source directories of **both** `hydrilla-builder` and `hydrilla`, run the build and installation commands:
``` shell
python3 -m build --no-isolation
python3 -m pip install dist/hydrilla*.whl # or use the full file name
```

[^pypi]: [https://pypi.org/](https://pypi.org/)
[^pypi_freeware]: [https://pypi.org/search/?c=License+%3A%3A+Freeware](https://pypi.org/search/?c=License+%3A%3A+Freeware)

## Testing
For tests to pass you need compiled message catalogs to be present. If you've performed the build at least once, they're already there. Otherwise, you need to run `./setup.py compile_catalog`. Then you can run the actual tests:
``` shell
python3 -m pytest
```

## Debian package
*TODO*

## Running

### Hydrilla command

Hydrilla includes a `hydrilla` shell command that can be used to quickly and easily spawn a local instance, e.g.:
```
hydrilla -m /path/to/where/package/files/to/serve/are/stored -p 10112
```
This will cause the resources from provided path to be served at [http://127.0.0.1:10112/](http://127.0.0.1:10112/).

The actual packages to serve are made using [Hydrilla builder](https://git.koszko.org/hydrilla-builder/).

For more information about available options, pass the `--help` flag to `hydrilla` command:
``` shell
hydrilla --help
```

If you navigate your POSIX shell to Hydrilla sources directory, you can also consult the included manpage (`man` tool required):
``` shell
man ./doc/man/man1/hydrilla.1
```

Last but not least, you might find it useful to consult the default, internal configuration file of Hydrilla that resides under `src/hydrilla/server/config.json` in the sources repository.

## Copying

Hydrilla is Copyright (C) 2021-2022 Wojtek Kosior and contributors, entirely available under the GNU Affero General Public License version 3 or later. Some files might also give you broader permissions, see comments inside them.

*I, Wojtek Kosior, thereby promise not to sue for violation of this project's license. Although I request that you do not make use this code in a proprietary program, I am not going to enforce this in court.*

## Contributing

Please visit our Redmine instance at https://hydrillabugs.koszko.org.

You can also write an email to koszko@koszko.org.