toolshed/docs.coopcloud.tech
3
1
Fork 21
Code Issues 4 Pull Requests 1 Packages Releases Activity

Compare commits

base: toolshed:translation
Branches Tags
toolshed:main toolshed:lambdabundesverband-patch-1 toolshed:auto-menu toolshed:migrate-021 toolshed:resolutions-march toolshed:add/karrot-joining-resolution toolshed:decap-cms toolshed:010-budget-format toolshed:translation knoflook:recipe-explanation knoflook:glossary knoflook:main
..
compare: knoflook:recipe-explanation
Branches Tags
knoflook:recipe-explanation knoflook:glossary knoflook:main toolshed:main toolshed:lambdabundesverband-patch-1 toolshed:auto-menu toolshed:migrate-021 toolshed:resolutions-march toolshed:add/karrot-joining-resolution toolshed:decap-cms toolshed:010-budget-format toolshed:translation

1 Commits
translatio ... recipe-exp

Author SHA1 Message Date
knoflook
5d62414a90 add recipe structure description
Some checks failed
continuous-integration/drone/pr Build is failing
Details
2021-11-25 16:44:40 +01:00
60 changed files with 1817 additions and 2286 deletions
Expand all files Collapse all files

1
.dockerignore
View File

@ -1 +0,0 @@
.venv

8
.drone.yml
View File

@ -1,8 +1,8 @@
--- ---
kind: pipeline kind: pipeline
name: publish name: deploy to swarm.autonomic.zone
steps: steps:
- name: build static - name: bundle static
image: plugins/docker image: plugins/docker
settings: settings:
username: thecoopcloud username: thecoopcloud
@ -18,7 +18,7 @@ steps:
deploy_key: deploy_key:
from_secret: drone_ssh_swarm.autonomic.zone from_secret: drone_ssh_swarm.autonomic.zone
depends_on: depends_on:
- build static - bundle static
- name: notify coopcloud-dev on failure - name: notify coopcloud-dev on failure
image: plugins/matrix image: plugins/matrix
@ -29,7 +29,7 @@ steps:
accesstoken: accesstoken:
from_secret: autonobot_rocketchat_access_token from_secret: autonobot_rocketchat_access_token
depends_on: depends_on:
- build static - bundle static
- deployment - deployment
when: when:
status: status:

8
Dockerfile
View File

@ -1,11 +1,13 @@
FROM squidfunk/mkdocs-material:9.0.12 FROM squidfunk/mkdocs-material:5.5.14
EXPOSE 8000 EXPOSE 8000
COPY . /docs COPY . /docs
WORKDIR /docs ENTRYPOINT ["/bin/sh"]
RUN apk add --no-cache curl RUN apk add --no-cache curl
RUN pip install mkdocs-awesome-pages-plugin mkdocs-material-extensions RUN pip install mkdocs-awesome-pages-plugin
CMD ["-c", "mkdocs build && python -m http.server --bind 0.0.0.0 --directory site 8000"]

680
LICENSE
View File

@ -1,6 +1,674 @@
Copyright (C) 2022 Co-op Cloud GNU GENERAL PUBLIC LICENSE
Permission is granted to copy, distribute and/or modify this document under the Version 3, 29 June 2007
terms of the GNU Free Documentation License, Version 1.3 or any later version
published by the Free Software Foundation; with no Invariant Sections, no Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included Everyone is permitted to copy and distribute verbatim copies
in the section entitled "GNU Free Documentation License". of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
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 <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<https://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<https://www.gnu.org/licenses/why-not-lgpl.html>.

8
README.md
View File

@ -3,11 +3,3 @@
[![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/docs.coopcloud.tech/status.svg)](https://build.coopcloud.tech/coop-cloud/docs.coopcloud.tech) [![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/docs.coopcloud.tech/status.svg)](https://build.coopcloud.tech/coop-cloud/docs.coopcloud.tech)
> https://docs.coopcloud.tech > https://docs.coopcloud.tech
## hacking
```
make
```
Theme docs are [here](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/) and [there](https://squidfunk.github.io/mkdocs-material/reference/).

1
compose.yml
View File

@ -12,7 +12,6 @@ services:
timeout: 10s timeout: 10s
retries: 10 retries: 10
start_period: 15s start_period: 15s
command: serve -a 0.0.0.0:8000 --no-livereload
deploy: deploy:
update_config: update_config:
failure_action: rollback failure_action: rollback

87
custom_theme/partials/header.html
View File

@ -1,87 +0,0 @@
{#-
This file was copied from the Material theme
You can find the file in .venv/lib/python3.10/site-packages/material/partials/header.html
-#}
{% set class = "md-header" %}
{% if "navigation.tabs.sticky" in features %}
{% set class = class ~ " md-header--lifted" %}
{% endif %}
<header class="{{ class }}" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="{{ lang.t('header.title') }}">
<a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
{% include "partials/logo.html" %}
</a>
<label class="md-header__button md-icon" for="__drawer">
{% include ".icons/material/menu" ~ ".svg" %}
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
{{ config.site_name }}
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
{% if page and page.meta and page.meta.title %}
{{ page.meta.title }}
{% else %}
{{ page.title }}
{% endif %}
</span>
</div>
</div>
</div>
{% if not config.theme.palette is mapping %}
<form class="md-header__option" data-md-component="palette">
{% for option in config.theme.palette %}
{% set primary = option.primary | replace(" ", "-") | lower %}
{% set accent = option.accent | replace(" ", "-") | lower %}
<input class="md-option" data-md-color-media="{{ option.media }}" data-md-color-scheme="{{ option.scheme }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}" {% if option.toggle %} aria-label="{{ option.toggle.name }}" {% else %} aria-hidden="true" {% endif %} type="radio" name="__palette" id="__palette_{{ loop.index }}">
{% if option.toggle %}
<label class="md-header__button md-icon" title="{{ option.toggle.name }}" for="__palette_{{ loop.index0 or loop.length }}" hidden>
{% include ".icons/" ~ option.toggle.icon ~ ".svg" %}
</label>
{% endif %}
{% endfor %}
</form>
{% endif %}
{% if config.extra.alternate %}
<div class="md-header__option">
<div class="md-select">
{% set icon = config.theme.icon.alternate or "material/translate" %}
<button class="md-header__button md-icon" aria-label="{{ lang.t('select.language.title') }}">
{% include ".icons/" ~ icon ~ ".svg" %}
</button>
<div class="md-select__inner">
<ul class="md-select__list">
{% for alt in config.extra.alternate %}
<li class="md-select__item">
<a href="{{ alt.link | url }}" hreflang="{{ alt.lang }}" class="md-select__link">
{{ alt.name }}
</a>
</li>
{% endfor %}
</ul>
</div>
</div>
</div>
{% endif %}
{% if config.repo_url %}
<div class="md-header__source">
{% include "partials/source.html" %}
</div>
{% endif %}
{% if "search" in config["plugins"] %}
<label class="md-header__button md-icon" for="__search">
{% include ".icons/material/magnify.svg" %}
</label>
{% include "partials/search.html" %}
{% endif %}
</nav>
{% if "navigation.tabs.sticky" in features %}
{% if "navigation.tabs" in features %}
{% include "partials/tabs.html" %}
{% endif %}
{% endif %}
</header>

34
docs/abra.md Normal file
View File

@ -0,0 +1,34 @@
---
title: Abra
---
## Enable auto-completion
### Bash
Copy `scripts/autocomplete/bash` into `/etc/bash_completion.d/` and rename
it to abra.
```
sudo cp scripts/autocomplete/bash /etc/bash_completion.d/abra
source /etc/bash_completion.d/abra
```
In development, you can source the script in your git checkout, just make sure
to set `PROG=abra`, otherwise it'll add completion to the wrong command:
```
PROG=abra source /path/to/abra/scripts/autocomplete/bash
```
### (Fi)Zsh
(fi)zsh doesn't have an autocompletion folder by default but you can create one, then copy `scripts/autocomplete/zsh` into it and add a couple lines to your `~/.zshrc` or `~/.fizsh/.fizshrc`
```
sudo mkdir /etc/zsh/completion.d/
sudo cp scripts/autocomplete/zsh /etc/zsh/completion.d/abra
echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
```
(replace .zshrc with ~/.fizsh/.fizshrc if you use fizsh)

52
docs/abra/cheat-sheet.md
View File

@ -1,52 +0,0 @@
---
title: Cheat sheet
---
# Abra cheat sheet
!!! info
not all flags are listed here.
!!! warning
Definitely set up autocomplete or you'll be sad
`abra autocomplete bash/zsh/fizsh`
### create and deploy a new app:
- `abra app new $RECIPE`
flags: `-s/--server`, `-D/--domain`, `-S/--secrets`, `-p/--pass`
- `abra app config $APPNAME`
- `abra app secret generate $APPNAME -a`
flags: `-p/--pass`, `-a/--all`
- `abra app deploy $APPNAME`
flags: `-f/--force`, `-C/--chaos`
### undeploy and remove an app
- back up any data you don't want to lose
- `abra app undeploy $APPNAME`
- `abra app rm --volumes $APPNAME`
flags: `-f/--force`, `-V/--volumes`
### add/remove server
- `abra server add $SERVER $USERNAME $SSH_PORT`
flags: `-p/--provision`, `-l/--local`
- `abra server remove $SERVER`
flags: `-s/--server`
### upgrade abra
- `abra upgrade`
flags: `--rc`
### upgrade a recipe
- `abra recipe upgrade $RECIPE`
flags: `-x,y,z/--major,minor,patch`
- `abra recipe sync $RECIPE`
flags: `-x,y,z`
- `abra recipe release $RECIPE [$VERSION]`
flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
### make a change to a recipe
- edit the files in `~/.abra/recipe/$RECIPENAME`
- deploy the changed version to your test instance
- determine how serious your change is (semver.org for reference)
- `abra recipe release $RECIPE [$VERSION]`

61
docs/abra/hack.md
View File

@ -1,61 +0,0 @@
---
title: Hack
---
## Quick start
Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/coop-cloud/abra).
Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. This will set coopcloud repos as private due to [this bug.](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/issues/20#issuecomment-8201). Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is.
Install [Go >= 1.16](https://golang.org/doc/install) and then:
- `make build` to build
- `./abra` to run commands
- `make test` will run tests
- `make install` will install it to `$GOPATH/bin`
- `go get <package>` and `go mod tidy` to add a new dependency
Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/.drone.yml) runs a number of sanity on each pushed commit. See the [Makefile](./Makefile) for more handy targets.
Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
### Cross-compiling
If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/coop-cloud/abra) and then:
- enter the `abra` directory
- run `git tag -l` to see the list of tags, choose the latest one
- run `git checkout <tag>`, where `<tag>` is the latest version
- run `GOOS=<os> GOARCH=<arch> [GOARM=<arm>] make build`. You only have to use `GOARM` if you're building for ARM, this specifies the ARM version (5,6,7 etc). See [this](https://go.dev/doc/install/source#environment) for a list of all supported OS'es and architectures.
## Release management
We use [goreleaser](https://goreleaser.com) to help us automate releases. We use [semver](https://semver.org) for versioning all releases of the tool. While we are still in the public beta release phase, we will maintain a `0.y.z-beta` format. Change logs are generated from our commit logs. We are still working this out and aim to refine our release praxis as we go.
For developers, while using this `-beta` format, the `y` part is the "major" version part. So, if you make breaking changes, you increment that and _not_ the `x` part. So, if you're on `0.1.0-beta`, then you'd go to `0.1.1-beta` for a backwards compatible change and `0.2.0-beta` for a backwards incompatible change.
### Making a new release
- Change `ABRA_VERSION` to match the new tag in [`scripts`](./scripts/installer/installer) (use [semver](https://semver.org))
- Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
- Make a new tag (e.g. `git tag -a x.y.z-beta`)
- Push the new tag (e.g. `git push && git push --tags`)
- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/abra)
- Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
- Check the release worked, (e.g. `abra upgrade; abra -v`)
## Fork maintenance
### `godotenv`
We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get github.com/Autonomic-Cooperative/godotenv@<commit>` where `<commit>` is the latest commit you want to pin to. At time of writing, `go get github.com/Autonomic-Cooperative/godotenv@b031ea1211e7fd297af4c7747ffb562ebe00cd33` is the command you want to run to maintain the above functionality.
### `docker/client`
A number of modules in [pkg/upstream](./pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
### `github.com/schultz-is/passgen`
Due to [`coop-cloud/organising#358`](https://git.coopcloud.tech/coop-cloud/organising/issues/358).

15
docs/abra/index.md
View File

@ -1,15 +0,0 @@
---
title: Abra
---
<a href="https://github.com/egonelbre/gophers"><img align="right" width="250" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
`abra` is the flagship client & command-line for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of operators and maintainers pleasant & convenient. It is libre software, written in Go and maintained and extended by the community :heart:
Once you've got `abra` installed, you can start your own Co-op Cloud deployment. `abra` allows you to create, deploy and maintain libre software apps. It supports working with existing servers or can create new servers (supported providers: [Servers.coop](https://servers.coop/) & [Hetzner](https://hetzner.com)). It can also help you manage your DNS configuration (supported providers: [Gandi](https://gandi.net)).
- [Install](/abra/install): You want to install `abra` :100:
- [Quick start](/abra/quickstart): You're ready to get started using `abra` :muscle:
- [Upgrade](/abra/upgrade): You're looking for instructions on how to upgrade `abra` :arrow_heading_up:
- [Hack](/abra/hack): You wan to hack on `abra` and help out with the development :woman_construction_worker:
- [Troubleshoot](/abra/trouble): `abra` ain't working and you'd like to know why :boom:

33
docs/abra/install.md
View File

@ -1,33 +0,0 @@
---
title: Install
---
## Stable release
```
curl https://install.abra.coopcloud.tech | bash
```
## Release candidate
```
curl https://install.abra.coopcloud.tech | bash -s -- --rc
```
## Installer script source
You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
## Using Docker
```
docker run \
-v $HOME/.abra:/.abra \
git.coopcloud.tech/coop-cloud/abra app ls
```
!!! note
If you're using symlinks, e.g. for [sharing
`~/.abra`](/operators/handbook/#sharing-abra), add more `-v` options for each
directory you're symlinking to, e.g. `-v
$HOME/Projects/CoopCloud/apps:/home/user/Projects/CoopCloud/apps`

11
docs/abra/quickstart.md
View File

@ -1,11 +0,0 @@
---
title: Quick start
---
There are a few ways to get started, here are some entrypoints listed below:
- If you're new around here and you'd like to learn how to deploy apps with `abra`, then a good place to start is the [new operators tutorial](/operators/tutorial). If you've already deployed some apps and would like to learn how to maintain them, then the [operators handbook](/operators/handbook) is the right place.
- If you're installing `abra` so you can do recipe packaging, take a look at the [new maintainers tutorial](/maintainers/tutorial). `abra` can help you check the quality of the recipe you've packaged and help you publish it to the public recipe catalogue. Then others can deploy your configuration :rocket:
If you run into any issues, please see the [troubleshooting page](/abra/trouble) :bomb:

105
docs/abra/trouble.md
View File

@ -1,105 +0,0 @@
---
title: Troubleshoot
---
## Where do I report `abra` bugs / feature requests?
You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/abra/issues/new).
## SSH connection issues?
`abra` tries its best to learn from your system configuration or command-line input what the correct SSH connection details are for a given server. This doesn't always work out. Here are some things to try to fix it.
First, ensure that you can `ssh <my-server>` and things work. If you can't SSH to your server then neither can `abra`. If you have a password protected SSH key, then you'll need to make sure your `ssh-agent` is running and you've added your SSH key part:
```
eval $(ssh-agent -k)
ssh-add ~/.ssh/<my-secret-key-part>
ssh-add -L # validate loaded keys
```
The first thing `abra` will check for is the connection details listed in `abra server ls`. Check those details are correct. If you haven't managed to `abra server add` your server yet, then no details will appear in that list. You may need to take a look at [this entry](/abra/trouble/#abra-server-ls-shows-the-wrong-details) to clean up old values depending on your situation.
`abra` will then try to read your `~/.ssh/config` entries and match the server domain against a `Host` entry. So, if you do `ssh myserver.com` and you have:
```
Host myserver.com
Hostname myserver.com
User myuser
Port 222
IdentityFile ~/.ssh/my@myserver.com
```
Then `abra` should have all it needs to build a working SSH connection. You can validate this by passing `-d/--debug` to your commands.
However, sometimes, you use an alias in your SSH configuration, say:
```
Host mys
...
```
So that you can simply type `ssh mys`. `abra` won't be able to match against those entries to discover connection details. You can use aliases to remedy this:
```
Host mys, myserver.com
...
```
`abra` will try to read the relevant `IdentityFile` entry from your `~/.ssh/config` but if it can't make a match, it will rely on your key being added to the `ssh-agent`.
Due to a limitation in our implementation, `abra` uses 2 methods of making SSH connections, the main `abra` -> `remote docker` connection using `/usr/bin/ssh` which can seamlessly pick up loaded SSH keys. However, for SSH host key checking, `abra` uses an SSH library & Golang SSH internals. We're working on resolving this to a single implementation but it is tricky work.
## "abra server ls" shows the wrong details?
You can use `abra server rm` to remove the incorrect details. Make sure to take a backup of your `~/.abra/servers/<domain>` first. You can then try to re-create by using `abra server add ...` again, making sure to take care if you need to use `<user> <port>`, see `abra server add -h` for more help on this.
However, if you have Docker installed on the same machine you have `abra`, then there might be some confusion. If you run `docker context ls` you'll see that Docker uses context connection strings also. `abra` simply uses this approach. Sometimes, your Docker defined context details & your `abra` context details can get out of sync. You can use `docker context rm` to resolve this.
If you need to create a new context from Docker, you can do:
```
docker context create <domain> --docker "host=ssh://<user>@<domain>:<port>"
```
(This is what we used to before we wrote `abra` to make it more convenient.)
## Command-line flag handling is weird?
Unfortunately, there is a limitation in our underlying command-line library implementation for `abra` ([ref](https://github.com/urfave/cli/issues/1113)) (and more fundamentally in the design of flags in the Go programming language itself ([ref](https://utcc.utoronto.ca/~cks/space/blog/programming/GoFlagUIImportance))). We're aiming to work with upstream to resolve the flag handling but this it is not yet clear when this will be resolved.
Currently, the following example of flexible flag usage is supported:
```
abra app new gitea -S # generate secrets, after args
abra app new -S gitea # generate secrets, before args
```
But something like the following does not work as expected:
```
abra app new -S gitea -p
```
Where the position of flags is mixed before & after args. `-p` is ignored :cry:
We're still waiting for upstream patch which resovles this.
## Why can't `abra` support multiline in `.env` files?
We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/coop-cloud/organising/issues/291) for more.
## I need some feature from the old deprecated bash abra?
There is an archive of the [old code here](https://git.coopcloud.tech/coop-cloud/abra-bash).
You can install it alongside the [supported version of Abra](https://git.coopcloud.tech/coop-cloud/abra) by using these commands:
```bash
git clone https://git.coopcloud.tech/coop-cloud/abra-bash ~/.abra/bash-src
ln -s ~/.abra/bash-src/abra ~/.local/bin/babra
```
## I am seeing very weird `lookup <domain> on <ip>: write udp <ip>: write: operation not permitted` errors
You should turn off your VPN. `abra` has trouble dealing with it right now. We welcome change sets to make it work though!

84
docs/abra/upgrade.md
View File

@ -1,84 +0,0 @@
---
title: Upgrade
---
## Release channels
### Stable
```
abra upgrade
```
### Release candidate
```
abra upgrade --rc
```
## Migration guides
### `0.6.x-beta` -> `0.7.x-beta`
> **ALERTA, ALERTA**: this is currently only available via the release
> candidate channel, using `abra upgrade --rc`. There has been a lot of churn
> and we're being cautious about releasing this one. Please help us test! We're
> currently on `0.7.0-rc2-beta`.
- `kadabra`, the app auto-updater is available for general alpha testing! See [these docs](https://docs.coopcloud.tech/operators/tutorial/#automatic-upgrades) for how to get started. Binaries can be found [here](https://git.coopcloud.tech/coop-cloud/abra/releases/tag/0.7.0-rc2-beta).
- **ALERTA, ALERTA**, security related issue: all `$domain.env` env vars are now exposed to the deployment via the `app` service container. Each `FOO=BAR` is exported within the context of the container. If you have any privately committed secrets in your `.env` files, please migrate them to the `secrets: ...` configuration in the recipe. This change was made to facilitate tooling which can support auto-upgrading of apps in a deployment.
- `abra` can no longer install Docker, initialise swarm mode and the proxy network. It will check if a Docker install exists and is in swarm mode or not and error out accordingly. We leave the provisioning to tools that are designed for that and reduce the command-line surface that we have to maintain going forward.
- `abra server add <host> <args>` 👉 `abra server add <host>`. We have finally removed the custom SSH handling code and now solely rely on invoke `/usr/bin/ssh` directly and reading from the `~/.ssh/config`. The `<host>` argument should correspond to a `Host <host>` entry in your `~/.ssh/config` or in an `Include <file>` statement (hosts are retrieved via `ssh -G <host>`). This means "how does `abra` interact with SSH is 1) do you have an `~/.ssh/config` entry for `<host>` 2) can you `ssh <host>` successfully? 3) there is no 3. It's an easier mental model and also the way `abra-bash` works, hence, less weird obscure errors. `<host>` being public a domain name is still required.
- `abra` no longer tries to do the TOFU host key verification prompt. We follow the praxis of the Docker CLI and just give up when host keys are not validated. We leave it to folks to SSH in and verify themselves.
- On the way to [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/pulls/268), several changes regarding labelling deployments have been merged in this release. This will allow tooling to understand a deployment without having the context of a `~/.abra/...` configuration. This will pave the way for server-side tooling, like `kadabra` which can help operators with different kinds of maintenance tasks.
- Welcome `abra recipe fetch`, which helps retrieve a recipe repository to your local work-station.
- Also say hello to `abra app services <domain>`, which lists the in-deployment service names and corresponding image, e.g. `foo_example_com`.
- Digests have been removed from the catalogue generation.
- Backup files generated by `abra` have a much more human-friendly format.
- Linting for domains is disabled when no `DOMAIN=...` is discovered in the `$odmain.env` file.
### `0.5.x-beta` -> `0.6.x-beta`
- Using `{{ .Domain }}` in recipe `.envrc.sample` files went away because it
was portable enough. We revert to replacing e.g `gitea.example.com` with the
domain. See
[`8fad34e`](https://git.coopcloud.tech/coop-cloud/abra/commit/8fad34e) for
more.
- If your `abra.sh` scripts depend on `/bin/sh` and `/bin/bash` is available in
the container then `/bin/bash` will be used from now on. `/bin/sh` is only
now used if `/bin/bash` is not available. See
[`7f745ff`](https://git.coopcloud.tech/coop-cloud/abra/commit/7f745ff) for
more.
### `v0.4.x` -> `v0.5.x`
- The only breaking change was making `abra` understand that the JSON dump for the recipes listing lives on [recipes.coopcloud.tech/recipes.json](https://recipes.coopcloud.tech) instead of [recipes.coopcloud.tech](https://recipes.coopcloud.tech).
### `v0.3.x` -> `v0.4.x`
Make sure to back up your `~/.abra/servers` configurations first for safety.
- Please run `mv ~/.abra/apps ~/.abra/recipes`.
- "app name" as a concept went away, `abra` now uses the domain name of an app as the identifier. However, we don't expect to see breaking behaviour if you have `.env` files like `~/.abra/servers/foo.com/mycoolapp.env` and you still want to run `abra app ps mycoolapp`. `abra` still reads the filename to figure out the identifier. When running `abra app new <recipe>`, `abra` will now take the domain name as the name of the `.env` file.
- `abra` has a new SSH implementation which enforces SSH host key checking. You may run into connection issues as a result of this code churn, please see [this entry](/abra/trouble/#ssh-connection-issues) for help navigating a fix.
- CLI flag/args handling has been made more flexible. We're working within the constraints of an upstream library issue but have hopefully made it easier to mange passing flags to commands with `abra`. See [this troubleshooting entry](/abra/trouble/#command-line-flag-handling-is-weird) for the full review.
- A number of short style flags have been re-mapped and/or added. This is again related to an issue with the upstream CLI library which sometimes understands short style flags as long style flags. E.g. `--ch` instead of `-ch` for `--chaos`. As a concrete example, `--ch` is now `-C` on `abra app deploy`.
- `abra app backup` & `abra app restore` are ready for alpha-testing! See [this entry](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore) and [that entry](https://docs.coopcloud.tech/operators/handbook/#how-do-i-backuprestore-my-app) for more.
- `abra server add --traefik` went away, it was too unreliable & hard to maintain.

15
docs/app-config-guide.md Normal file
View File

@ -0,0 +1,15 @@
---
title: App config guide
---
The tips that were previously on this page have moved to the relevant recipe README files, to keep everything in one place while we figure out the best long-term home for per-app documentation. Find the READMEs here:
- [Keycloak][keycloak]
- [Nextcloud][nextcloud]
- [Drone][drone]
- [Peertube][peertube]
[keycloak]: https://git.coopcloud.tech/coop-cloud/keycloak
[nextcloud]: https://git.coopcloud.tech/coop-cloud/nextcloud
[drone]: https://git.coopcloud.tech/coop-cloud/drone
[peertube]: https://git.coopcloud.tech/coop-cloud/peertube

145
docs/apps.md Normal file
View File

@ -0,0 +1,145 @@
---
title: Application catalogue
---
<!-- DO NOT EDIT TABLES MANUALLY
App information is auto-generated with abra/app-catalogue.sh:
https://git.autonomic.zone/coop-cloud/abra/src/branch/main/app-catalogue.sh
Manual edits will be over-written the next time that script is run.
-->
An experimental version of this catalogue is available here:
https://dev.apps.coopcloud.tech
## Applications
| **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Adapt Authoring Tool](https://git.autonomic.zone/coop-cloud/adapt_authoring) | ❸🍎 | ❹💣 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [alerta](https://git.autonomic.zone/coop-cloud/alerta) | | 0 | | | | | |
| [botamusique](https://git.autonomic.zone/coop-cloud/botamusique) | | | | | | | |
| [calendso](https://git.autonomic.zone/coop-cloud/calendso) | | 4 | ❌ | ❌ | ✅ | ❌ | ⛔ |
| [capsul](https://git.autonomic.zone/coop-cloud/capsul) | ❸🍎 | ❹💣 | ✅ | ❌ | ❶💚 | ❷💛 | ❌ |
| [CiviCRM-Backdrop](https://git.autonomic.zone/coop-cloud/civicrm-backdrop) | ❹💣 | ? | ❌ | ❌ | ❌ | ❌ | ❌ |
| [collabora](https://git.autonomic.zone/coop-cloud/collabora) | ❶💚 | ❶💚 | ❌ | ❌ | ❶💚 | ❷💛 | ❌ |
| [cryptpad](https://git.autonomic.zone/coop-cloud/cryptpad) | | | | | | | |
| [Custom HTML](https://git.autonomic.zone/coop-cloud/custom-html) | ❷💛 | ❶💚 | ❌ | ❌ | ⛔ | ❷💛 | ❌ |
| [Discourse](https://git.autonomic.zone/coop-cloud/discourse) | | [`bitnami/discourse`](https://hub.docker.com/r/bitname/discourse) | yes | no | yes | no | no |
| [Drone](https://git.autonomic.zone/coop-cloud/drone) | 1, alpha | ❶💚 | ✅ | ? | ? | ❷💛 | ❶💚 (OAuth) |
| [Federated Wiki](https://git.autonomic.zone/coop-cloud/federatedwiki) | ❹💣 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Filerun](https://git.autonomic.zone/coop-cloud/filerun) | 0, work-in-progress | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Filestash](https://git.autonomic.zone/coop-cloud/filestash) | ❹💣 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [foodsoft](https://git.autonomic.zone/coop-cloud/foodsoft) | | 4 | | | | | |
| [ghost](https://git.autonomic.zone/coop-cloud/ghost) | | | | | | | |
| [Gitea](https://git.autonomic.zone/coop-cloud/gitea) | ❶💚 | ❶💚 | ✅ | ✅ | ? | ❷💛 | (OAuth) |
| [H5ai](https://git.autonomic.zone/coop-cloud/h5ai) | ❸🍎 | ❸🍎 | ✅ | ❌ | ⛔ | ❌ | ❌ |
| [Hedgedoc](https://git.autonomic.zone/coop-cloud/hedgedoc) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❶💚 (OAuth) |
| [Hometown](https://git.autonomic.zone/coop-cloud/hometown) | | [`decentral1se/hometown`](https://hub.docker.com/r/decentral1se/hometown) | | | | | |
| [Invoiceninja](https://git.autonomic.zone/coop-cloud/invoiceninja) | ❹💣 | ❸🍎 | ❌ | ❌ | ? | ❌ | ? |
| [Jupyter Lab](https://git.autonomic.zone/coop-cloud/jupyter-lab) | 1 | `jupyter/datascience-notebook` | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [keycloak](https://git.autonomic.zone/coop-cloud/keycloak) | ❷💛 | ❶💚 | ✅ | ? | ❸🍎 | ❷💛 | ⛔ |
| [Keyoxide](https://git.autonomic.zone/coop-cloud/keyoxide) | ❷💛 | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ⛔ |
| [Kimai](https://git.autonomic.zone/coop-cloud/kimai) | ? | ❷💛 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [Kutt](https://git.autonomic.zone/coop-cloud/kutt) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [laplace](https://git.autonomic.zone/coop-cloud/laplace) | | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [levelfly](https://git.autonomic.zone/coop-cloud/levelfly) | | 4 | | | | | |
| [Loomio](https://git.autonomic.zone/coop-cloud/loomio) | ❹💣 | [`loomio/*`](https://hub.docker.com/r/loomio) | ❌ | ❌ | ? | ❌ | ❌ |
| [mailman3](https://git.autonomic.zone/coop-cloud/mailman3) | 1, alpha | [`maxking/mailman-*`](https://github.com/maxking/docker-mailman) | | | | | |
| [Mailu](https://git.autonomic.zone/coop-cloud/mailu) | ❸🍎 | ❶💚 | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [Mastodon](https://git.autonomic.zone/coop-cloud/mastodon) | | [`tootsuite/mastodon`](https://hub.docker.com/r/tootsuite/mastodon) | | | | | |
| [Matomo](https://git.autonomic.zone/coop-cloud/matomo) | ❸🍎 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [Matrix (Synapse)](https://git.autonomic.zone/coop-cloud/matrix-synapse) | ❹💣 | ❶💚 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Mediawiki](https://git.autonomic.zone/coop-cloud/mediawiki) | ❸🍎 | ❶💚 | ❌ | ✅ | ❶💚 | ❷💛 | ❷💛 (OAuth, SAML) |
| [monica](https://git.autonomic.zone/coop-cloud/monica) | | ❶💚 | no | no | ❶💚 | ❷💛 | no |
| [mumble](https://git.autonomic.zone/coop-cloud/mumble) | ❸🍎 | ❸🍎3rdparty | ❌ | ❌ | ⛔ | ❌ | ⛔ |
| [Nextcloud](https://git.autonomic.zone/coop-cloud/nextcloud) | ❷💛 | ❶💚 | ✅ | ❌ | ❶💚 | ❷💛 | ❸🍎 (OAuth) |
| [notea](https://git.autonomic.zone/coop-cloud/notea) | ❹💣 | [`notea`](https://hub.docker.com/r/cinwell/notea) | ❌ | ❌ | ❌ | ❌ | ❌ |
| [oasis](https://git.autonomic.zone/coop-cloud/oasis) | 0, work-in-progress | | | | | | |
| [onlyoffice](https://git.autonomic.zone/coop-cloud/onlyoffice) | ❶💚 | ❶💚 | ❌ | ❌ | ❶💚 | ❷💛 | ❌ |
| [Osticket](https://git.autonomic.zone/coop-cloud/osticket) | 0, work-in-progress | [`osticket`](https://hub.docker.com/r/osticket/osticket) | | | | | |
| [Outline](https://git.autonomic.zone/coop-cloud/outline) | | [outlinewiki/outline](https://hub.docker.com/r/outlinewiki/outline) | | | | | |
| [Pelican](https://git.autonomic.zone/coop-cloud/pelican) | ❷💛 | ❹💣 | ❌ | ❌ | ⛔ | ❷💛 | ❌ |
| [Penpot](https://git.autonomic.zone/coop-cloud/penpot) | ❹💣 | [`penpotapp/*`](https://hub.docker.com/r/penpotapp) | | | | | |
| [PHP / LEMP](https://git.autonomic.zone/coop-cloud/lemp) | ❶💚 | ❶💚 | ✅ | ✅ | ❶💚 | ❷💛 | ❌ |
| [PHPServerMon](https://git.autonomic.zone/coop-cloud/phpservermon) | 0, work-in-progress | ❸🍎 | | ❌ | ❌ | ❌ | ❌ |
| [plausible](https://git.autonomic.zone/coop-cloud/plausible) | 1, alpha | ❶💚 | | | | | |
| [Projectsend](https://git.autonomic.zone/coop-cloud/projectsend) | 0, work-in-progress | ❸🍎 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Radicale](https://git.autonomic.zone/coop-cloud/radicale) | ❹💣 | ❸🍎 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Rocket.chat](https://git.autonomic.zone/coop-cloud/rocketchat) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❶💚 (OAuth) |
| [Rstudio](https://git.autonomic.zone/coop-cloud/rstudio) | | [`rstudio`](https://hub.docker.com/r/rstudio/rstudio) | | | | | |
| [Selfoss](https://git.autonomic.zone/coop-cloud/selfoss) | ❸🍎 | ❸🍎 | ✅ | ❌ | ❌ | ❸🍎 | ⛔ |
| [singlelink](https://git.autonomic.zone/coop-cloud/singlelink) | 0, work-in-progress | | | | | | |
| [snikket](https://git.autonomic.zone/coop-cloud/snikket) | | [`thecoopcloud/snikket-*`](https://hub.docker.com/u/thecoopcloud) | | | | | |
| [Statping](https://git.autonomic.zone/coop-cloud/statping) | ❸🍎 | ❶💚 | ❌ | ❌ | ❸🍎 | ❌ | ❌ |
| [Statuspal](https://git.autonomic.zone/coop-cloud/statuspal) | 0, work-in-progress | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Strapi](https://git.autonomic.zone/coop-cloud/strapi) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [vaultwarden](https://git.autonomic.zone/coop-cloud/vaultwarden) | | | | | | | |
| [Wallabag](https://git.autonomic.zone/coop-cloud/wallabag) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [Wordpress](https://git.autonomic.zone/coop-cloud/wordpress) | ❶💚 | ❶💚 | ✅ | ✅ | ❶💚 | ❷💛 | ❌ |
| [Workadventure](https://git.autonomic.zone/coop-cloud/workadventure) | ❹💣 | [`thecodingmachine/workadventure*`](https://hub.docker.com/r/thecodingmachine/) | ❌ | ❌ | ❌ | ❌ | ❌ |
| [ZNC](https://git.autonomic.zone/coop-cloud/znc) | ❹💣 | ❸🍎 | ❌ | ❌ | ❌ | ❌ | ❌ |
## Utilities
| **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [AWX](https://git.autonomic.zone/coop-cloud/AWX) | 0, work-in-progress | | | | | | |
| [Backupbot II](https://git.autonomic.zone/coop-cloud/backup-bot-two) | 0, work-in-progress | 4 | ❌ | ⛔ | ⛔ | ❌ | ⛔ |
| [container](https://git.autonomic.zone/coop-cloud/container) | 1, alpha | any | ❌ | ❌ | ❌ | ❌ | ❌ |
| [croc](https://git.autonomic.zone/coop-cloud/croc) | ❶💚 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [distribution](https://git.autonomic.zone/coop-cloud/distribution) | 0, work-in-progress | ❶💚 | ? | ? | ? | ? | ? |
| [Docker-Hub-RSS](https://git.autonomic.zone/coop-cloud/docker-hub-rss) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [drone-docker-runner](https://git.autonomic.zone/coop-cloud/drone-docker-runner) | 1, alpha | ❶💚 | ? | ? | ? | ? | ? |
| [go-neb](https://git.autonomic.zone/coop-cloud/go-neb) | ❹💣 | ❶💚 | | | | | |
| [go-ssb-room](https://git.autonomic.zone/coop-cloud/go-ssb-room) | ❹💣 | ❹💣 | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [Jupyter Lab](https://git.autonomic.zone/coop-cloud/n8n) | 1 | `n8nio/n8n` | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [keycloak-collective-portal](https://git.autonomic.zone/coop-cloud/keycloak-collective-portal) | 1, alpha | [`decentral1se/keycloak-collective-portal`](https://hub.docker.com/r/decentral1se/keycloak-collective-portal) | ✅ | ❌ | ⛔ | ✅ | ⛔ |
| [minio](https://git.autonomic.zone/coop-cloud/minio) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [portainer](https://git.autonomic.zone/coop-cloud/portainer) | ? | ❶💚 | ❌ | ? | ? | ❷💛 | ❌ |
| [Postfix-Relay](https://git.autonomic.zone/coop-cloud/postfix-relay) | ❷💛 | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ⛔ |
| [renovate](https://git.autonomic.zone/coop-cloud/renovate) | | | | | | | |
| [swarm-cronjob](https://git.autonomic.zone/coop-cloud/swarm-cronjob) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [Swarmpit](https://git.autonomic.zone/coop-cloud/swarmpit) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ⛔ |
| [traefik-forward-auth](https://git.autonomic.zone/coop-cloud/traefik-forward-auth) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [Traefik](https://git.autonomic.zone/coop-cloud/traefik) | ? | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ? (Keycloak) |
## Status legend
### Overall
- 🌈🌈: everything in ❶💚 + Single-Sign-On
- ❶💚: upstream image, backups, email, healthcheck, integration testing
- ❷💛: upstream image, missing 1-2 items from ❶💚
- ❸🍎: missing 3-4 items from ❶💚 or no upstream image
- ❹💣: alpha
### Image
- ❶💚: official upstream image
- ❷💛: semi-official / actively-maintained image
- ❸🍎: 3rd-party image
- ❹💣: our own custom image
### Email
- ❶💚: automatic (using environment variables)
- ❷💛: mostly automatic
- ❸🍎: manual
- ❌: none
### CI
- ❶💚: as ❷💛, plus healthcheck
- ❷💛: auto secrets + networks
- ❸🍎: basic deployment using `stack-ssh-deploy`, manual secrets + networks
- ❌: none
### Single-Sign-On
- ❶💚: automatic (using environment variables)
- ❷💛: mostly automatic
- ❸🍎: manual
- ❌: none
- 💣: not supported

61
docs/backup-restore.md Normal file
View File

@ -0,0 +1,61 @@
---
title: Back-up and restore an app
---
We'll use the example of a [`coop-cloud/wordpress`][wordpress] app deployed at
`blog.example.com`.
## Backing up
```
abra app wordpress_blog_example_com backup --all
```
This will download backups of the Wordpress files (plugins, themes, and uploads)
and database (posts, settings and users) to the default backup directory,
`~/.abra/backups`.
You can also back up just the files:
```
abra app wordpress_blog_example_com backup app
```
or just the database:
```
abra app wordpress_blog_example_com backup db
```
!!! warning
Not all types of apps know how to do backups yet -- if you see a message
like `ERROR: 'nextcloud' doesn't know how to do app backups`, then extra
code is needed in that app's `abra.sh` -- you might be able to add this
yourself based on [`coop-cloud/wordpress` `abra.sh`][wordpress_abra.sh],
otherwise please open a new issue (in this case for
[`coop-cloud/nextcloud`][nextcloud]).
## Restore
You can restore data into a running application. This is useful to restore an
app to a previous state, to migrate an app from one Co-op Cloud server to
another, or to help move an app to Co-op Cloud initially.
Using the same example app above, you can restore files:
```
abra app wordpress_blog_example_com restore app blog_example_com_app.tar.gz
```
and/or the database:
```
abra app wordpress_blog_example_com restore db blog_example_com_db.sql.gz
```
(there isn't yet a command to restore files and database data at the same time)
[wordpress]: https://git.autonomic.zone/coop-cloud/wordpress
[wordpress_abra.sh]: https://git.autonomic.zone/coop-cloud/wordpress/src/branch/master/abra.sh
[nextcloud]: https://git.autonomic.zone/coop-cloud/nextcloud

9
docs/bikemap.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Bike map
---
- The project is currently in an [alpha quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) release state.
- We are working towards a [beta release](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta).
- We do not currently have an exact for the public Beta release yet.
- Our public Beta goals are listed in the following pad: [beta bike map](https://pad.autonomic.zone/s/C3uuqfSCk)
- What we're currently working on is listed on this issue tracker: [`coop-cloud/organising`](https://git.autonomic.zone/coop-cloud/organising/issues)

35
docs/comm-org.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Community Organising
---
## Monthly updates on progress
We have decided we'll try to do monthly progress updates. These will be published on the Co-op Cloud blog.
It's a pretty loose format and we're basically just copy/pasta'ing things to a public pad during the month:
> [This month in Co-op Cloud](https://pad.autonomic.zone/YHKn4vHORmS6wjN1t2zi5A?both)
Feel free to add your items to the monthly agenda and they will be included!
## Kite Flying Hours
The "Kite Flying Hour" is a weekly public moment where anyone can "drop by" into a Jitsi call and ask/do/propose whatever and meet some people who are currently working on the project. We haven't worked it all out but our process for now is the following:
- Someone from Autonomic will volunteer to be present and talk about the project for an hour weekly from 15:00 CEST - 16:00 CEST
- We announce the hour via our socials
- A [pinned toot](https://social.coop/web/statuses/106528094828958420) on [`@coopcloud@social.coop`](https://social.coop/@coopcloud)
- A [pinned tweet](https://twitter.com/Coop_Cloud/status/1412028519056609286) on [`@Coop_Cloud`](https://twitter.com/Coop_Cloud)
- A post to the `#coopcloud:autonomic.zone` room
Here is some invitation boilerplate which you can use:
> Hey folks, you're all warmly invited to the Co-op Cloud Kite Flying Hour at `$X_TIME` `$Y_TZ` `$Z_DATE` over in [meet.jit.si/CoopCloudKiteFlyingHour](https://meet.jit.si/CoopCloudKiteFlyingHour)!
>
> Inspired by exquisite childhood memories of [flying kites, eating popsicles and looking at clouds](https://norwichhistory.org/norwich-a-z-j-is-for-jigsaw/), it's an open hour to come hang out online and discuss/co-work/lurk/etc. around the [Co-op Cloud](https://coopcloud.tech/) project.
>
> There are no "stupid questions"! It's a space to inquire, be curious and have a good time and get to know each other.
>
> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/LqotfSJJRj69RcTtWmr7iw). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
>
> Hope to see you there! ☁️ 🌞 🖥️

108
docs/config.md Normal file
View File

@ -0,0 +1,108 @@
---
title: Manage your app configuration
---
## Understanding app and server configuration
Co-op Cloud stores per-app configuration in the `$USER/.abra/servers` directory, on whichever machine you're running `abra` on (by default, your own workstation).
The format of these configuration files is the same environment variable syntax used by Docker (with the `env_file:` statement in a `docker-compose.yml` file, or the `--env-file` option to `docker run`) and `direnv`:
```
abra app example_wordpress config
TYPE=wordpress
DOMAIN=wordpress.example.com
## Domain aliases
EXTRA_DOMAINS=', `www.wordpress.example.com`'
LETS_ENCRYPT_ENV=production
...
```
`abra` doesn't mind if `~/.abra/servers`, or any of its subdirectories, is a [symlink], so you can keep your app definitions wherever you like!
```
mv ~/.abra/servers/ ~/coop-cloud
ln -s ~/coop-cloud ~/.abra/servers
```
## Backing up your app configuration
Just make sure the `~/.abra/servers` is included in the configuration of your favourite backup tool.
You can optionally also backup `~/.abra/apps`, if you'd like to keep an exact copy of the application versions you currently have deployed. Otherwise, they'll be automatically downloaded the first time you run an `abra app...` command.
You don't need to worry about `~/.abra/vendor` or `~/.abra/src` directories, which will be likewise recreated automatically as and when you need them.
<a id="version-control"></a>
## Version-control your app configs (using git)
Because `~/.abra/servers` is a collection of plain-text files, it's easy to keep your backup configuration in a version control system (we use `git`, others would almost certainly work).
This is particularly recommended if you're collaborating with others, so that you can all run `abra app...` commands without having to maintain your own separate, probably-conflicting, configuration files.
In the simple case where you only have one server configured with `abra`, or everyone in your team is using the same set of servers, you can version-control the whole `~/.abra/servers` directory:
```
cd ~/.abra/servers
git init
git add .
git commit -m "Initial import"
```
!!! warning "Test your revision-control self-discipline"
`abra` does not yet help keep your app definitions are up-to-date.
Make sure to run `git add` / `git commit` after making configuration changes, and `cd ~/.abra/servers && git pull` before running `abra app...` commands.
Patches to add some safety checks and auto-updates would be very welcome! 🙏
## Collaborating with multiple teams
In a more complex situation, where you're using Co-op Cloud to manage several servers, and you're collaborating with different people on different servers, you can set up **a separate repository for each subdirectory in `~/.abra/servers`**, or even a mixture of single-server and multi-server repositories:
```
ls -l ~/.abra/servers
# Example.com's own app configuration:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.example.com -> /home/user/Example/coop-cloud-apps/swarm.example.com
# Configuration for one of Example.com's clients – part of the same repository:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.client.com -> /home/user/Example/coop-cloud-apps/swarm.client.com
# A completely separate project, part of a different repository:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.demonstration.com -> /home/user/Demonstration/coop-cloud-apps
```
To make setting up these symlinks easier, you might want to include a simple installer script in your configuration repositories.
We don't have a public example of this yet, but something like this should do the trick:
1. Save this as `Makefile` in your repository:
```
# -s symlink, -f force creation, -F don't create symlink in the target dir
link:
@mkdir -p ~/.abra/servers/
@for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \
echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
done
```
This will set up symlinks from each directory in your repository to a correspondingly-named directory in `~/.abra/servers` – if your repository has a `swarm.example.com` directory, it'll be linked as `~/.abra/servers/swarm.example.com`.
2. Tell your collaborators (e.g. in the repository's `README`), to run `make` in their repository check-out.
!!! warning "You're on your own!"
As with the [simple repository set-up above](#version-control), `abra` doesn't yet help you update your version control system when you make changes, nor check version control to make sure you have the latest configuration.
Make sure to `commit` and `push` after you make any configuration changes, and `pull` before running any `abra app...` commands.
## Even more granularity?
The plain-text, file-based configuration format means that you could even keep the configuration for different apps on the same server in different repositories, e.g. having `git.example.com` configuration in a separate repository to `wordpress.example.com`, using per-file symlinks.
We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage _any_ app in that swarm**.
[symlink]: https://en.wikipedia.org/wiki/Symlink

12
docs/contact.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Get in Touch
---
We're available on the following channels:
- **Email**: [`helo@coopcloud.tech`](mailto:helo@coopcloud.tech)
- **Real-time chat (Matrix)**:
- [`#coopcloud:autonomic.zone`](https://matrix.to/#/!JSVYWCRXSVMrAzgeKB:autonomic.zone?via=autonomic.zone) General chat and announcements (low traffic)
- [`#coopcloud-tech:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Technical discussions (some techno babble)
- [`#coopcloud-dev:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Intense developer chat (a lot of techno babble)
- **Forum**: [`community.coops.tech`](https://community.coops.tech/)

39
docs/contribute.md Normal file
View File

@ -0,0 +1,39 @@
---
title: Contributing guide
---
> You don't have to be a programmer to contribute to this project!
Firstly, come say hello in our [chat room](/contact/) if you'd like to help out
:wave: We are happy to have designers, thinkers, hackers, documenters, etc.
involved in this project! There is a lot of work to do, if you find this
project interesting, we want to have you working with us.
We have [a weekly check-in](/comm-org/#kite-flying-hours) for contributors of
this project to let each other know what we're working on, how much time we've
spent on it and how to coordinate further work.
We have a [public bike map](https://pad.autonomic.zone/s/C3uuqfSCk) showing
what we are aiming to achieve in the near future. That gives a good overview
of where we're going together.
From this bike map, we use an [issue
tracker](https://git.coopcloud.tech/coop-cloud/organising/issues) where we hold
discussions about what we want to do. We categorise these issues according to
the bike map using these
[milestones](https://git.coopcloud.tech/coop-cloud/organising/milestones).
Finally, use this
[board](https://git.coopcloud.tech/coop-cloud/organising/projects/8) to keep
track of what we're working on right now. We collectively review these things
on a weekly/monthly basis to keep track of our time spent vs. budget available.
Once you've found something to work on and are introduced, we'll give you an
account on our [time tracking infrastructure](https://kimai.autonomic.zone)
where you can log your times. This helps us reduce the burden of financial and
time keeping admin falling on one person.
We have received funding via [the
ECF](https://culturalfoundation.eu/initiatives/culture-of-solidarity-fund) and
can offer £16 hourly rate for your work. We've written
[more](/strategy/#compensation-for-contributions) on why we think it is
important to compensate all contributions for this project.

2
docs/intro/credits.md → docs/credits.md
View File

@ -9,5 +9,3 @@ Special thanks to:
- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing. - [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing.
- [Social.coop](https://social.coop), for warmly welcoming us onto [`social.coop/@coopcloud`](https://social.coop/@coopcloud). - [Social.coop](https://social.coop), for warmly welcoming us onto [`social.coop/@coopcloud`](https://social.coop/@coopcloud).
- [Servers.coop](https://servers.coop), for hosting our digital infrastructure (website, builds, git hosting, etc.). - [Servers.coop](https://servers.coop), for hosting our digital infrastructure (website, builds, git hosting, etc.).
- Every single last one of you heroic & patient beta testers, you are all comrades of the highest order of kropotkin :heart:
- [`egonelbre/gophers`](https://github.com/egonelbre/gophers) for the rad gopher logos

5
docs/democracy/decisions.md
View File

@ -1,5 +0,0 @@
---
title: Decisions
---
Placeholder for all the wonderful decisions we will make together.

5
docs/democracy/index.md
View File

@ -1,5 +0,0 @@
---
title: Democracy
---
Placeholder for all the wonderful things we will do together.

145
docs/deploy.md Normal file
View File

@ -0,0 +1,145 @@
---
title: Deploy your first app
---
In order to deploy an app you need two things:
1. a server (e.g. [Hetzner VPS](https://www.hetzner.com/cloud)), with
- SSH access
- a public IP address
2. a DNS provider (e.g. [Gandi](https://www.gandi.net/en))
## Create your server
Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/faq/#isnt-running-everything-in-containers-inefficient)). We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html). You may also be interested in this [FAQ entry](/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
## Wire up your DNS
Typically, you'll need two A records, one to point to the VPS itself and another to support sub-domains for the apps. You can then support an app hosted on your root domain (e.g. `example.com`) and other apps on sub-domains (e.g. `foo.example.com`, `bar.example.com`). Your entries in your DNS provider setup might look like the following.
@ 1800 IN A 116.203.211.204
*. 1800 IN A 116.203.211.204
Where `116.203.211.204` can be replaced with the IP address of your server.
## Install server prerequisites
You'll want to install [Docker](https://www.docker.com/) on your server. This can be done by following the [install documentation](https://docs.docker.com/engine/install/).
## Bootstrap `abra`
Once your DNS and docker daemon are up, you can install [`abra`](https://git.coopcloud.tech/coop-cloud/abra) locally on your developer machine and hook it up to your server.
Firstly, install `abra` locally.
```bash
curl https://install.abra.autonomic.zone | bash
```
The source for this script [is here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
the installer will verify the checksum. If you want to download abra yourself, you can grab it from the [releases page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the checksums.txt file. If you decide to do this, please run:
```bash
grep $(sha256sum abra_[version]_[platform]) checksums.txt > /dev/null && echo "checksum OK"
```
if "checksum OK" appears in your terminal - you're good to go! otherwise, you have downloaded a corrupted file.
You may need to add the `~/.local/bin/` directory with your `$PATH` in order to run the executable.
```bash
export PATH=$PATH:$HOME/.local/bin
abra -h # check it works
```
Now you can connect `abra` with your new server.
```bash
abra server add example.com
```
Where `example.com` is replaced with your server DNS name.
!!! note "About SSH"
`abra` uses Docker's built-in SSH support to make a secure connection to a
remote Docker daemon, to deploy and manage apps from your local development
machine.
If you need to specify a non-standard port, and/or different username, for SSH,
add them as extra arguments:
```bash
abra server add -p example.com username 2222
```
The `-p` or `--provision` flag means that abra will initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server.
You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance. You can easily share this as a git repository with others.
## Deploy Traefik
In order to have your Co-op cloud installation automagically provision SSL certificates, we will first install [Traefik](https://doc.traefik.io/traefik/). This tool is the main entrypoint for all web requests (e.g. like NGINX) and supports automatic SSL certificate configuration and other quality-of-life features which make deploying libre apps more enjoyable.
```bash
abra app new traefik
```
You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value:
```bash
abra app config traefik
```
Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
```
abra app deploy traefik
```
## Deploy Nextcloud
And now we can deploy apps.
Let's create a new Nextcloud app.
```bash
abra app new nextcloud
```
And we need to generate secrets for the app: database connection password, root password and admin password.
```bash
abra app secret generate --all nextcloud
```
!!! warning
Take care, these secrets are only shown once on the terminal so make sure
to take note of them! `abra` makes use of the [Docker secrets](/secrets/)
mechanism to ship these secrets securely to the server and store them as
encrypted data.
Then we can deploy the Nextcloud.
```bash
abra app deploy nextcloud
```
We can watch to see that things come up correctly.
```bash
abra app ps nextcloud # status check
abra app logs nextcloud # logs watch
```
!!! note
Since Nextcloud takes some time to come up live, you can run the `ps`
command under `watch` like so.
```bash
watch abra app ps nextcloud
```
And you can wait until you see that all containers have the "Running" state.
Your `traefik` instance will detect that a new app is coming up and generate SSL certificates for it.

44
docs/intro/faq.md → docs/faq.md
View File

@ -12,7 +12,7 @@ The project was started by workers at [Autonomic](https://autonomic.zone/) which
## Why Co-op Cloud? ## Why Co-op Cloud?
#### Pros #### 👍
- 👍 Thin "ease of use" layer on top of already standardised tooling - 👍 Thin "ease of use" layer on top of already standardised tooling
- 👍 Extremely modular - 👍 Extremely modular
@ -23,7 +23,7 @@ The project was started by workers at [Autonomic](https://autonomic.zone/) which
- 👍 Command line focussed - 👍 Command line focussed
- 👍 Horizontal and vertical scaling - 👍 Horizontal and vertical scaling
#### Cons #### 👎
- 👎 Still a very young project - 👎 Still a very young project
- 👎 Limited availability of well tested apps - 👎 Limited availability of well tested apps
@ -36,9 +36,9 @@ Please read our [initial project announcement post](https://autonomic.zone/blog/
Also see our [strategy page](/strategy/). Also see our [strategy page](/strategy/).
## How do I make a recipe for (package) an app? ## How do I package an app?
See ["Package your first recipe"](/maintainers/tutorial/#package-your-first-recipe) for more. See [the packager guide documentation](/packager-guide/#package-your-first-application) for more.
## What about `$alternative`? ## What about `$alternative`?
@ -48,14 +48,14 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
### Cloudron ### Cloudron
#### Pros #### 👍
- 👍 Decent web interface for app, domain & user management. - 👍 Decent web interface for app, domain & user management.
- 👍 Large library of apps. - 👍 Large library of apps.
- 👍 Built-in SSO using LDAP, which is compatible with more apps and often has a better user interface than OAuth. - 👍 Built-in SSO using LDAP, which is compatible with more apps and often has a better user interface than OAuth.
- 👍 apps are actively maintained by the Cloudron team. - 👍 apps are actively maintained by the Cloudron team.
#### Cons #### 👎
- 👎 Moving away from open source. The core is now proprietary software. - 👎 Moving away from open source. The core is now proprietary software.
- 👎 libre tier has a single app limit. - 👎 libre tier has a single app limit.
@ -70,7 +70,7 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
### YunoHost ### YunoHost
#### Pros #### 👍
- 👍 Lovely web interface for app, domain & user management. - 👍 Lovely web interface for app, domain & user management.
- 👍 Bigger library of apps. - 👍 Bigger library of apps.
@ -79,7 +79,7 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
- 👍 Doesn't require a public-facing IP. - 👍 Doesn't require a public-facing IP.
- 👍 Supports system-wide mutualisation of resources for apps (e.g. sharing databases by default) - 👍 Supports system-wide mutualisation of resources for apps (e.g. sharing databases by default)
#### Cons #### 👎
- 👎 Upstream libre software communities aren't involved in packaging. - 👎 Upstream libre software communities aren't involved in packaging.
- 👎 Uninstalling apps leaves growing cruft. - 👎 Uninstalling apps leaves growing cruft.
@ -88,7 +88,7 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
### Caprover ### Caprover
#### Pros #### 👍
- 👍 Bigger library of apps. - 👍 Bigger library of apps.
- 👍 Easy set-up using a DigitalOcean one-click app. - 👍 Easy set-up using a DigitalOcean one-click app.
@ -96,7 +96,7 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
- 👍 Deploy any app with a `docker-compose.yml` file as a "One Click App" via the web interface. - 👍 Deploy any app with a `docker-compose.yml` file as a "One Click App" via the web interface.
- 👍 Multi-node (multi-server) set-up works by default. - 👍 Multi-node (multi-server) set-up works by default.
#### Cons #### 👎
- 👎 Single-file app definition format, difficult to tweak using entrypoint scripts. - 👎 Single-file app definition format, difficult to tweak using entrypoint scripts.
- 👎 Nginx instead of Traefik for load-balancing. - 👎 Nginx instead of Traefik for load-balancing.
@ -107,30 +107,30 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
### Ansible ### Ansible
#### Pros #### 👍
- 👍 Includes server creation and bootstrapping. - 👍 Includes server creation and bootstrapping.
#### Cons #### 👎
- 👎 Upstream libre software communities aren't publishing Ansible roles - 👎 Upstream libre software communities aren't publishing Ansible roles
- 👎 Lots of manual work involved in things like app isolation, backups, updates - 👎 Lots of manual work involved in things like app isolation, backups, updates
### Kubernetes ### Kubernetes
#### Pros #### 👍
- 👍 Helm charts are available for some key apps already. - 👍 Helm charts are available for some key apps already.
- 👍 Scale all the things. - 👍 Scale all the things.
#### Cons #### 👎
- 👎 Too big -- requires 3rd party tools to run a single-node instance. - 👎 Too big -- requires 3rd party tools to run a single-node instance.
- 👎 Not suitable for a small to mid size hosting provider. - 👎 Not suitable for a small to mid size hosting provider.
### Docker-compose ### Docker-compose
#### Pros #### 👎
- 👎 Manual work required for process monitoring. - 👎 Manual work required for process monitoring.
- 👎 Secret storage not available yet. - 👎 Secret storage not available yet.
@ -138,11 +138,11 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n
### Doing it Manually (Old School) ### Doing it Manually (Old School)
#### Pros #### 👍
- 👍 Simple - just follow upstream instructions to install and update. - 👍 Simple - just follow upstream instructions to install and update.
#### Cons #### 👎
- 👎 Loads of manual work required for app isolation and backups. - 👎 Loads of manual work required for app isolation and backups.
- 👎 Array of sysadmin skills required to install and maintain apps. - 👎 Array of sysadmin skills required to install and maintain apps.
@ -178,7 +178,7 @@ We definitely recommend using best-in-class security auditing tools like [docker
It's up to how you want to arrange your system. For example, Co-op Cloud also allows you to compartmentalise different apps onto different servers. You could stack a bunch of apps on one big server or you could deploy one app per server. It's up to how you want to arrange your system. For example, Co-op Cloud also allows you to compartmentalise different apps onto different servers. You could stack a bunch of apps on one big server or you could deploy one app per server.
These are organisational concerns that Co-op Cloud can't solve for you which any software system will require. See this [additional question](/intro/faq/#what-is-important-to-consider-when-running-containers-in-production) for further information. These are organisational concerns that Co-op Cloud can't solve for you which any software system will require. See this [additional question](/faq/#what-is-important-to-consider-when-running-containers-in-production) for further information.
## What is important to consider when running containers in production? ## What is important to consider when running containers in production?
@ -210,7 +210,7 @@ We are happy to see the compose specification emerging as a new open standard be
## Why Docker Swarm? ## Why Docker Swarm?
While many have noted that "swarm is dead" it is in fact [not dead](https://www.mirantis.com/blog/mirantis-will-continue-to-support-and-develop-docker-swarm/). As detailed in the [architecture overview](/operators/tutorial/#container-orchestrator), swarm offers an appropriate feature set which allows us to support zero-down time upgrades, seamless app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design. While many have noted that "swarm is dead" it is in fact [not dead](https://www.mirantis.com/blog/mirantis-will-continue-to-support-and-develop-docker-swarm/). As detailed in the [architecture overview page](/overview/#container-orchestrator), swarm offers an appropriate feature set which allows us to support zero-down time upgrades, seamless app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design.
While the industry is bordering on a [k8s](https://kubernetes.io/) obsession and the need to [scale down](https://microk8s.io/) a tool that was fundamentally built for massive scale, we are going with swarm because it is the tool most suitable for [small technology](https://small-tech.org/). While the industry is bordering on a [k8s](https://kubernetes.io/) obsession and the need to [scale down](https://microk8s.io/) a tool that was fundamentally built for massive scale, we are going with swarm because it is the tool most suitable for [small technology](https://small-tech.org/).
@ -222,6 +222,8 @@ If you want to learn more, see [dockerswarm.rocks](https://dockerswarm.rocks/) f
The Co-op Cloud is and will always be available under [copyleft licenses](https://en.wikipedia.org/wiki/Copyleft). The Co-op Cloud is and will always be available under [copyleft licenses](https://en.wikipedia.org/wiki/Copyleft).
We're discussing more specifics on [this issue](https://git.autonomic.zone/coop-cloud/organising/issues/50) if you'd like to see the on-going conversation.
## Isn't running everything in containers inefficient? ## Isn't running everything in containers inefficient?
It is true that if you install 3 apps and each one requires a MySQL database, then you will have 3 installations of MySQL on your system, running in containers. It is true that if you install 3 apps and each one requires a MySQL database, then you will have 3 installations of MySQL on your system, running in containers.
@ -248,6 +250,4 @@ Yes! Horizontal scaling is one of the ways Co-op Cloud can really shine. `abra`
## Why only x86 support? ## Why only x86 support?
We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.autonomic.zone/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/). We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.autonomic.zone/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](https://docs.coopcloud.tech/contact/).
Update: [Can I run Co-op Cloud on ARM?](/operators/handbook/#can-i-run-co-op-cloud-on-arm)

39
docs/get-involved/index.md
View File

@ -1,39 +0,0 @@
---
title: Get Involved
---
## Overview
> :trumpet: **You don't have to be a programmer to contribute to this project!** :trumpet:
Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or are interested to learn how :wave:
We are happy to have designers, critical thinkers, artists, hackers, documenters, etc. involved in this project! There is a lot of work to do, if you find this project interesting, we want to have you working with us.
There are a number of "roles" such as "operator", "maintainer", "organiser" which we've tried to come up with to make it more clear how you can relate to the project and how you can find ways to be involved which suit your interests. If you don't fit one of these roles, that is fine.
We have [a weekly check-in](/get-involved/#kite-flying-hours) for contributors of this project to let each other know what we're working on, how much time we've spent on it and how to coordinate further work.
We have a [status page](/intro/bikemap) showing what we are aiming to achieve in the near future. That gives a good overview of where we're going together.
From this status page, we use an [issue tracker](https://git.coopcloud.tech/coop-cloud/organising/issues) where we hold discussions about what we want to do. We categorise these issues according to the bike map using these [milestones](https://git.coopcloud.tech/coop-cloud/organising/milestones). Finally, use this [board](https://git.coopcloud.tech/coop-cloud/organising/projects/8) to keep track of what we're working on right now. We collectively review these things on a weekly/monthly basis to keep track of our time spent vs. budget available.
Once you've found something to work on and are introduced, we'll give you an account on our [time tracking infrastructure](https://kimai.autonomic.zone) where you can log your times. This helps us reduce the burden of financial and time keeping admin falling on one person.
We have received funding via [the ECF](https://culturalfoundation.eu/initiatives/culture-of-solidarity-fund) and can offer £16 hourly rate for your work. We've written more on why we think it is important to compensate all contributions for this project below.
## Compensation
We think that it is important to focus on making the libre software ecosystem sustainable. This has historically [not been the case](https://www.fordfoundation.org/media/2976/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure.pdf). It feels important to contextualise this position. In the words of [LURK](https://lurk.org):
> Big tech and an abusive misunderstanding of free and open source software practices have led us to believe that software production, server maintenance and on-line services should be free as in gratis. However there is no such things as a free lunch and software does not exist in a vacuum. If we want sustainable alternatives and a diverse cultural sector, these alternatives and the humans behind them, need to be supported.
And a short excerpt from [Seven Theses On The Fediverse and The Becoming Of FLOSS](https://archive.transmediale.de/content/seven-theses-on-the-fediverse-and-the-becoming-of-floss):
> Without substantial funding for ongoing development and maintenance, these projects will remain contingent upon the exploitation of the free labor of well-meaning individuals, or subject to the whims of people making time for their FLOSS hobby.
We want to build a flourishing, inclusive, accessible project and paying people for their work (not just writing source code, but other forms of organising and care work too!) has a role to play in that. We think that making it possible to compensate contributors for working on Co-op Cloud is a way to get involved with self-organising sustainability from the start.
We haven't worked this all out. We've opened up an [Open Collective account](https://opencollective.com/coop-cloud) and we're running this as an "invite only mode" approach.
**If you want to make a contribution to Co-op Cloud and you'd like to be compensated, please [come and chat to us first](/intro/contact/).**

59
docs/glossary/index.md
View File

@ -1,59 +0,0 @@
---
title: Glossary
---
## Abra
A command-line tool that has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community. You can find the source [here](https://git.coopcloud.tech/coop-cloud/abra).
## App
An app is a libre software that you use, e.g. Wordpress, Gitea, Jitsi, Nextcloud, etc. When you `abra app deploy <domain>`, you deploy an app. It is quite an overloaded term in general, often referring to many different things. We struggled with using this word but it seems to be one word people recognise and have a point of reference for.
## Container
A [Docker](/glossary#docker) term: a running instance of an [image](/glossary#image), running processes that are isolated from the host system.
## Deployment
When you run `abra app deploy <domain>`, `abra` reads a [recipe](/glossary#recipe) configuration and creates an [app](/glossary#app).
## Docker
[Docker Inc.](https://www.docker.com/), the company who popularised the concept of [the container](https://www.docker.com/resources/what-container). The same company has created the underlying tools & libraries that `abra` uses to get work done.
## Environment variables
Variables passed from the shell to processes invoked by it. They are used for configuring [services](/glossary#service).
## Environment file
A file contained in a [recipe](/glossary#recipe) describing the contents of [environmental variables](/glossary#environment-variables).
## Image
A [Docker](/glossary#docker) term: a template for creating [containers](/glossary#container), describing their file structure and installed binaries.
## Proxy network
A [Docker](glossary#docker) related concept: a virtual network created on the server machine used for communicating between [services](/glossary#service). Any [service](/glossary#service) can be plugged into more than one [network](/glossary#network), allowing for control over data sharing between them.
## Recipe
A recipe is what we call the configuration files that are used to deploy an [app](/glossary#app). When you run `abra app deploy <domain>`, `abra` is reading a recipe configuration, such as [the gitea recipe](https://git.coopcloud.tech/coop-cloud/gitea), in order to know how to deploy a new Gitea instance. When we speak of a "digital configuration commons", we're primarily referring to the [growing collection of recipes](https://git.coopcloud.tech/coop-cloud).
## Secret
A [Docker](/glossary#docker) related concept: A way to store passwords encrypted on disk and mounted inside the [containers](/glossary#container) as files that can be read that contain the secret. See the [Docker secrets documentation for more](https://docs.docker.com/engine/swarm/secrets/). `abra` makes use of this approach to store secrets for deployed [apps](/glossary#app).
## Service
A [Docker](glossary#docker) term: a single [container](/glossary#container) that is a part of a [stack](glossary#stack).
## Stack
A [Docker](glossary#docker) term: one or more [services](/glossary#service) running together to provide a functionality.
## Volume
A [Docker](/glossary#docker) term: a directory that can be mounted inside a [container](/glossary#container) to store data. Because [containers](/glossary#container) are meant to be non-changeable and disposable, any data that is supposed to not be lost between updates or restarts is stored in volumes.

30
docs/index.md
View File

@ -1,33 +1,21 @@
--- ---
title: Introduction title: Co-op Cloud
--- ---
## Who is this for? Welcome to the Co-op Cloud technical documentation. It's primarily meant for co-ops and other democratic tech collectives already doing libre software hosting who are interested in the project and thinking about doing some alpha testing.
Welcome to the Co-op Cloud documentation 🥳 - New to the project and wondering where to start? Try our [getting started guide](/overview/).
The documentation is aimed at a technical audience: tech co-ops, collectives and individuals who are curious about Co-op Cloud or are already running and managing Co-op Cloud deployments. - Want to see what apps are already available? See the [app catalogue](https://dev.apps.coopcloud.tech).
A more general public may still find these pages useful but if you're just looking for a quick overview of the project from a less technical perspective, you can take a look at [coopcloud.tech](https://coopcloud.tech). - Trying to understand more about the project? See the [the FAQ](/faq/).
We'd be happy to hear feedback about our documentation, if it was helpful, what was missing, what was confusing, etc., please [get in touch](/intro/contact)! - Interested to learn more about the goals and background of the project? See the [strategy page](/strategy).
## Quick start
!!! danger "Here be dragons" !!! danger "Here be dragons"
This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/get-involved/). This project is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha). Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/contribute/).
- [Operators guide](/operators/): You run a Co-op Cloud based deployment or want to do so :computer: !!! note "Looking for managed Co-op Cloud hosting?"
- [Maintainers guide](/maintainers/): You maintain recipes and ensure things run smoothly for operators :tools: If you're looking for a co-operative or tech collective to host digital services for you using the Co-op Cloud, then please see [the managed hosting](/managed/) page for more.
- [Organisers guide](/organisers): You run meetings, write guidelines & shape our democratic process :fist:
- [Recipes](/recipes/): You want to know what recipes are packaged so you can deploy them as apps :nerd:
- [Abra](/abra): You want to install the command-line client and hack the planet :unicorn:
- [Get involved](/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
- [Glossary](/glossary/): You'd like clarification about project terminology :book:

33
docs/index.pl.md
View File

@ -1,33 +0,0 @@
---
title: Wstęp
---
## Who is this for?
Witaj w dokumentacji Co-op Cloud!
Ta dokumentacja jest skierowana do odbiorców "technicznych": spółdzielni technologicznych, kolektywów i osób indywidualnych zainteresowanych Co-op Cloud, lub takich, które mają już deploymenty Co-op Cloud.
A more general public may still find these pages useful but if you're just looking for a quick overview of the project from a less technical perspective, you can take a look at [coopcloud.tech](https://coopcloud.tech).
We'd be happy to hear feedback about our documentation, if it was helpful, what was missing, what was confusing, etc., please [get in touch](/intro/contact)!
## Quick start
!!! danger "Here be dragons"
This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/get-involved/).
- [Operators guide](/operators/): You run a Co-op Cloud based deployment or want to do so :computer:
- [Maintainers guide](/maintainers/): You maintain recipes and ensure things run smoothly for operators :tools:
- [Organisers guide](/organisers): You run meetings, write guidelines & shape our democratic process :fist:
- [Recipes](/recipes/): You want to know what recipes are packaged so you can deploy them as apps :nerd:
- [Abra](/abra): You want to install the command-line client and hack the planet :unicorn:
- [Get involved](/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
- [Glossary](/glossary/): You'd like clarification about project terminology :book:

9
docs/intro/bikemap.md
View File

@ -1,9 +0,0 @@
---
title: Bike map
---
- The project is currently in a [beta quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) release state.
- We are working towards a stable `1.0.0` release.
- What we're currently working on is listed on this issue tracker: [`coop-cloud/organising`](https://git.autonomic.zone/coop-cloud/organising/issues).

25
docs/intro/contact.md
View File

@ -1,25 +0,0 @@
---
title: Get in touch
---
## Email
[`helo@coopcloud.tech`](mailto:helo@coopcloud.tech)
## Chat
### Matrix
Here is a link to the [Matrix space](https://matrix.to/#/!xSMwGbdVehScXcIFwS:autonomic.zone?via=autonomic.zone&via=matrix.org&via=1312.media) to see all channels.
- [`#coopcloud:autonomic.zone`](https://matrix.to/#/!JSVYWCRXSVMrAzgeKB:autonomic.zone?via=autonomic.zone) General chat and announcements (low traffic)
- [`#coopcloud-tech:autonomic.zone`](https://matrix.to/#/!DfXPgKLoYCvjHithgS:autonomic.zone?via=autonomic.zone) Technical discussions (some techno babble)
- [`#coopcloud-dev:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Intense developer chat (a lot of techno babble)
### XMPP
> Coming Soon :tm:
## Forum
[`community.coops.tech`](https://community.coops.tech/)

13
docs/intro/managed.md
View File

@ -1,13 +0,0 @@
---
title: Managed hosting
---
!!! danger "We're still working this out, you can help too!"
If you're a co-operative or a tech collective who wants to appear on this list, please [get in touch](/intro/contact/)! We want to expand the number of service providers using the Co-op Cloud so that project is more widely available to end-users and organisations who can influence the direction and co-fund the development.
The Co-op Cloud is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: but you can still work with a tech co-op or collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.
- [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto:helo@autonomic.zone))
- [Local-IT](https://local-it.org/) (contact [`info@local-it.org`](mailto:info@local-it.org))
- [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))

19
docs/intro/strategy.md
View File

@ -1,19 +0,0 @@
---
title: Project strategy
---
!!! note "Yes, we are blog"
Some leading thoughts are outlined in the [project launch blog post](https://autonomic.zone/blog/co-op-cloud/) also.
From our experiences working and organising as Autonomic, the tech co-op who initiated Co-op Cloud, we know that the progressive tech movement lack reliable and cost-effective technical means for providing an alternative to “Big Tech” cloud services.
The urgency for providing an alternative comes out of the understanding that the concentration of our digital lives within the private sphere of corporate providers (e.g. [GAFAM](https://degooglisons-internet.org/en/)) represents a loss of freedom due to the threat to our privacy and self-determination through surveillance and monopolisation.
As a movement, we cannot compete with corporate providers in terms of cost and scale. Their network effects and available capital means that no one project, product or organisation can create the required shift to a more widespread public interest technology.
Technology alone will not save us. Simply deploying libre software is not enough.
Our strategy is to mutualise our resources to facilitate this shift. Co-op Cloud is an attempt to create a new shared resource - an open and democratically managed, open standards based, copyleft licensed, libre software infrastructure project.
From this base, we can focus on the urgent and necessary social organising work that goes beyond the technical question.

541
docs/maintainers/handbook.md
View File

@ -1,541 +0,0 @@
---
title: Packaging handbook
---
## Create a new recipe
You can run `abra recipe new <recipe>` to generate a new `~/.abra/recipes/<recipe>` repository. The generated repository is a copy of [`coop-cloud/example`](https://git.coopcloud.tech/coop-cloud/example).
## Hacking on an existing recipe
If you want to make changes to an existing recipe then you can simply edit the files in `~/.abra/recipes/<recipe-name>` and run pass `--chaos` to the `deploy` command when deploying those changes. `abra` will not deploy unstaged changes to avoid instability but you can tell it to do so with `--chaos`. This means ou can simple hack away on the existing recipe files on your local file system and then when something is working, submit a change request to the recipe upstream.
## How is a recipe structured?
### `compose.yml`
This is a [compose specification](https://compose-spec.io/) compliant file that contains a list of: services, secrets, networks, volumes and configs. It describe what is needed to run an app. Whenever you deploy an app, `abra` reads this file.
### `.env.sample`
This file is a skeleton for environmental variables that should be adjusted by the user. Examples include: domain or php extention list. Whenever you create a new app with `abra app new` this file gets copied to the `~/.abra/servers/<server-domain>/<app-domain>.env` and when you run `abra app config <app-domain>` you're editing this file.
### `abra.sh`
The `abra.sh` provides versions for configs that are vendored by the recipe maintainer. See [this handbook entry](/maintainers/handbook/#manage-configs) for more.
### `entrypoint.sh`
After docker creates the filesystem and copies files into a new container it runs what's called an entrypoint. This is usually a shell script that exports some variables and runs the application. Sometimes the vendor entrypoint doesn't do everything that we need it to do. In that case you can write your own entrypoint, do whatever you need to do and then run the vendor entrypoint.
For a simple example check the [entrypoint.sh for `croc`](https://git.coopcloud.tech/coop-cloud/croc/src/commit/2f06e8aac52a3850d527434a26de0a242bea0c79/entrypoint.sh). In this case, `croc` needs the password to be exported as an environmental variable called `CROC_PASS`, and that is exactly what the entrypoint does before running vendor entrypoint.
If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml. See [this handbook entry](http://localhost:8000/maintainers/handbook/#entrypoints) for more.
### `releases/` directory
This directory contains text files whose names correspond to the recipe versions which have been released and contain useful tips for operators who are doing upgrade work. See [this handbook entry](/maintainers/handbook/#how-do-i-write-version-release-notes) for more.
### Optional compose files
I.e. `compose.smtp.yml`. These are used to provide non-essential functionality such as (registration) e-mails or single sign on. These are typically loaded by specifying `COMPOSE_FILE="compose.yml:compose.smtp.yml"` in your app `.env` configuration. Then `abra` learns to include these optional files at deploy time. `abra` uses the usual `docker-compose` configuration merging technique when merging all the `compose.**.yml` files together at deploy time.
### Additional configs
If you look at a `compose.yml` file and see a `configs` section, that means this compose file is putting files in the container. This might be used for changing default (vendor) configuration, such as this [fpm-tune.ini file](https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/28425b6138603067021757de28c639ad464e9cf8/fpm-tune.ini) used to adjust `php-fpm.` See [this handbook entry](/maintainers/handbook/#manage-configs) for more.
## Manage configs
To add additional files into the container, you can use [Docker configs](https://docs.docker.com/engine/swarm/configs/). This usually involves the following:
1. Create the file and add it to your recipe repository
1. Create an entry for this config in your `configs: ...` global stanza
1. Create an entry on the service configuration `configs: ...` stanza
1. Vendor a version in the `abra.sh` of the recipe
An example of a config is an [entrypoint](/maintainers/handbook/#entrypoints), a script run at container run time.
```yaml
# compose.yml
services:
app:
configs:
- source: nginx_config
target: /etc/nginx/nginx.conf
configs:
nginx_config:
name: ${STACK_NAME}_nginx_config_${NGINX_CONFIG_VERSION}
file: nginx.conf.tmpl
template_driver: golang
```
Because configurations are maintained in-repository by maintainers, we version them ourselves. This means that configs changes are seamless to operators unless they cause breaking changes which should be signalled in the new version and release notes. This is in distinction to secrets, which are managed by the operators. For example, operators may need to rotate secrets on a running deployment and should be able to do so at any time. We put the versions in the [`abra.sh`](/maintainers/handbook/#abrash) file.
```bash
# abra.sh
export NGINX_CONFIG_VERSION=v1
```
## Manage environment variables
When you define an environment variable in a `.env.sample` for a recipe, such as:
```bash
FOO=123
```
And you pass this via the `environment` stanza of a service config in the recipe like so:
```yaml
service:
app:
environment:
- FOO
```
Then your environment variable will be threaded into the running app at deploy time. If you run `abra app run <domain> app env | grep FOO` then you'll see it exposed.
You can also access it in your configs using the following syntax:
```go
{{ env "FOO" }}
```
## Manage secret data
Adding a secret to your recipe is done:
1. Create an entry in the `secrets: ...` global stanza
1. Add the `<SECRET-NAME>_VERSION=v1` to your `.env.sample`
1. Ensure that the secret is listed on the service configuration under `secrets: ...`
It might look something like this:
```yaml
# compose.yml
services:
app:
secrets:
- db_password
secrets:
db_password:
external: true
name: ${STACK_NAME}_db_password_${SECRET_DB_PASSWORD_VERSION}
```
Operators manage the secret versions themselves. So we provide a version hook in the environment variables which they control. This allows operators to deal with things like secret rotation without having to rely on recipe maintainers.
```bash
# .env.sample
SECRET_DB_PASSWORD_VERSION=v1
```
If you need to access this secret in a config, say:
```yaml
configs:
someconfig:
name: ${STACK_NAME}_someconfig_${SOME_CONFIG_VERSION}
file: entrypoint.sh.tmpl
template_driver: golang
```
Don't forget the `template_driver: golang`, it won't work otherwise.
Then you can use the following syntax to access the secret:
```go
# someconfig.conf
{{ secret "db_password"}}
```
## Entrypoints
### Custom entrypoints
They can be useful to install additional dependencies or setup configuration that upstream doesn't have or want to have.
Here's a trimmed down config, the general idea is to create a new config and insert it into the container at a specific location and then have the compose configuration tell the underlying image to run this new script as the entrypoint.
You typically don't want to completely override the upstream entrypoint of the image you're using, so in the last line of your entrypoint, you can run the upstream entrypoint.
```yaml
services:
app:
entrypoint: /docker-entrypoint.sh
configs:
- source: app_entrypoint
target: /docker-entrypoint.sh
mode: 0555
configs:
app_entrypoint:
name: ${STACK_NAME}_app_entrypoint_${APP_ENTRYPOINT_VERSION}
file: entrypoint.sh.tmpl
template_driver: golang
```
### Exposing secrets
Sometimes apps expect to find a secret in their environment which is not possible with the default compose configuration approach. This requires a hack using an entrypoint. The hack is basically this (assume we want to expose a secret called `db_password`):
1. Setup the secret as per usual in `secrets: ...`
2. Pass a `DB_PASSWORD_FILE=/run/secrets/db_password` in via the `environment: ...`
3. Create an entrypoint and inside it, use the following boilerplate.
```bash
#!/bin/bash
set -e
file_env() {
local var="$1"
local fileVar="${var}_FILE"
local def="${2:-}"
if [ "${!var:-}" ] && [ "${!fileVar:-}" ]; then
echo >&2 "error: both $var and $fileVar are set (but are exclusive)"
exit 1
fi
local val="$def"
if [ "${!var:-}" ]; then
val="${!var}"
elif [ "${!fileVar:-}" ]; then
val="$(< "${!fileVar}")"
fi
export "$var"="$val"
unset "$fileVar"
}
```
And then to expose your secret to the container environment use the following in a line below this function:
```bash
file_env "DB_PASSWORD"
```
### `/bin/bash` is missing?
Sometimes the containers don't even have Bash installed on them. You had better just use `/bin/sh` or, in your entrypoint script, install Bash :upside_down: The entrypoint secrets hack listed above doesn't work in this case (as it requires Bash), so instead you can just do `export FOO=$(cat /run/secrets/<secret-name>)`.
## How do I reference services in configs?
When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using the often obscure dark magic of the Golang templating language). You can find examples of this approach used in the [Peertube recipe](https://git.coopcloud.tech/coop-cloud/peertube/src/commit/d1b297c5a6a23a06bf97bb954104ddfd7f736568/nginx.conf.tmpl#L9).
## How are recipes versioned?
We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
The Gitea project maintains a version, e.g. `1.14.3`. This version uses the [semver](https://semver.org) strategy for communicating what type of changes are included in each version, i.e., if there is a breaking change, Gitea will release a new version as `2.0.0`.
However, there are other types of changes that can happen for a recipe. Perhaps the database image gets a breaking update or the actual recipe configuration changes some environment variable. This can mean that end-users of the recipe need to do some work to make sure their updates will deploy successfully.
Therefore, we maintain an additional version part, in front of the project version. So, the first release of the Gitea recipe in the Co-op Cloud project has the version of `1.0.0+1.14.3`. This `x.y.z+` is the version part that the recipe maintainer manages. If a new available Gitea version comes out as `1.15` then the recipe maintainer will publish `1.1.0+1.15` as this is a backwards compatible update, following semantic versioning.
In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3` to `1.15.3`, we still publish `1.1.0+1.15.3` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
## How do I release a new recipe version?
The commands uses for dealing with recipe versioning in `abra` are:
- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
- `abra recipe release`: publish a git tag for the recipe repo
The `abra` recipe publishing commands have been designed to complement a semi-automatic workflow. If `abra` breaks or doesn't understand what is going on, you can always finish the process manually with a few Git commands and a bit of luck. We designed `abra` to support this way due to the chaotic nature of container publishing versioning schemes.
Let's take a practical example, publishing a new version of [Wordpress](https://git.coopcloud.tech/coop-cloud/wordpress).
If we run `abra recipe upgrade wordpress` (at time of running), we end up with a prompt to upgrade Wordpress to `5.9.0`. We can skip the database upgrade for now. Here is what that looks like:
```
➜ ~ abra recipe upgrade wordpress
? upgrade to which tag? (service: app, image: wordpress, tag: 5.8.3) 5.9.0
? upgrade to which tag? (service: db, image: mariadb, tag: 10.6) skip
WARN[0004] not upgrading mariadb, skipping as requested
```
Now, what happened? `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available. Once you make some choices on the prompt, `abra` will update the recipe configurations. Let's take a look by running `cd ~/.abra/recipes/wordpress && git diff`:
```diff
diff --git a/compose.yml b/compose.yml
index 1618ef5..6cd754d 100644
--- a/compose.yml
+++ b/compose.yml
@@ -3,7 +3,7 @@ version: "3.8"
services:
app:
- image: "wordpress:5.8.3"
+ image: "wordpress:5.9.0"
volumes:
- "wordpress_content:/var/www/html/wp-content/"
networks:
```
!!! warning "Here be versioning dragons"
`abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/coop-cloud/tagcmp) for more info on how we implement image parsing.
Next, we need to update the label in the recipe, we can do that with `abra recipe sync wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading from `5.8.3` -> `5.9.0`, it is a minor release, so we choose `minor`:
```
➜ wordpress (master) ✗ abra recipe sync wordpress
...
INFO[0088] synced label coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0 to service app
```
Once again, we can run `cd ~/.abra/recipes/wordpress && git diff` to see what `abra` has done for us:
```diff
diff --git a/compose.yml b/compose.yml
index 1618ef5..4a08db6 100644
--- a/compose.yml
+++ b/compose.yml
@@ -3,7 +3,7 @@ version: "3.8"
services:
app:
- image: "wordpress:5.8.3"
+ image: "wordpress:5.9.0"
volumes:
- "wordpress_content:/var/www/html/wp-content/"
networks:
@@ -48,7 +48,7 @@ services:
#- "traefik.http.routers.${STACK_NAME}.rule=HostRegexp(`{subdomain:.+}.${DOMAIN}`, `${DOMAIN}`)"
- "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
- "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
- - "coop-cloud.${STACK_NAME}.version=1.0.2+5.8.3"
+ - "coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0"
- "backupbot.backup=true"
- "backupbot.backup.path=/var/www/html"
```
You'll notice that `abra` figured out how to upgrade the Co-op Cloud version label according to our choice, `1.0.2` -> `1.1.0` is a minor update.
At this point, we're all set, we can run `abra recipe release --publish wordpress`. This will do the following:
1. run `git commit` the new changes
1. run `git tag` to create a new git tag named `1.1.0+5.9.0`
1. run `git push` to publish changes to the Wordpress repository
!!! warning "Here be more SSH dragons"
In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
Here is the output:
```
WARN[0000] discovered 1.1.0+5.9.0 as currently synced recipe label
WARN[0000] previous git tags detected, assuming this is a new semver release
? current: 1.0.2+5.8.3, new: 1.1.0+5.9.0, correct? Yes
new release published: https://git.coopcloud.tech/coop-cloud/wordpress/src/tag/1.1.0+5.9.0
```
And once more, we can validate this tag has been created with `cd ~/.abra/recipes/wordpress && git tag -l`.
## How are new recipe versions tested?
This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go.
Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release --publish <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `ugrade` so that it accepts the locally unstaged changes.
!!! warning "Here be more SSH dragons"
In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
It is good practice to take note of all the issues you ran into and share them with other operators. See [this entry](/maintainers/handbook/#how-do-i-write-version-release-notes) for more.
If you don't have time or are not an operator, reach out on our communication channels for an operator willing to do some testing.
## How do I write version release notes?
In the root of your recipe repository, run the following (if the folder doesn't already exist):
```
mkdir -p releases
```
And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
## How do I generate the recipe catalogue
To generate an entire new copy of the catalogue:
```
abra catalogue generate
```
You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
If you just want to generate a catalogue entry for a single recipe:
```
abra catalogue generate <recipe>
```
The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
```
cd ~/.abra/catalogue
git diff
```
You can pass `--publish` to have `abra` automatically publish those changes.
!!! warning "Here be more SSH dragons"
In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
## How do I enable healthchecks
A healthcheck is an important and often overlooked part of the recipe configuration. It is part of the configuration that the runtime uses to figure out if a container is really up-and-running. You can tweak what command to run, how often and how many times to try until you assume the container is not up.
There are no real univesal configs and most maintainers just pick up what others are doing and try to adapt. There is some testing involved to see what works well. You can browse the existing recipe repositories and see from there.
You'll often find the same one used for things like caches & supporting services, such as Redis:
```yaml
healthcheck:
test: ["CMD", "redis-cli", "ping"]
```
If you're just starting off with packaging a recipe, you can use `healthcheck: disable` until you have something working. It's definitely advised to work out your healthcheck as a last step, it can be a bit tricky.
`abra app errors -w <domain>` will show what errors are being reported from a failing healtcheck setup.
## How do I tune deploy configs?
A bit like healtchecks, there is no universal setup. A good default seems to be the following configuration:
```yaml
deploy:
update_config:
failure_action: rollback
order: start-first
rollback_config:
order: start-first
restart_policy:
max_attempts: 3
```
The `start-first` setting ensures that the container runtime tries to start up the new container and get it running before switching over to it.
Setting a restart policy is also good so that the runtime doesn't try to restart the container forever.
Best to [read](https://docs.docker.com/engine/reference/builder/#healthcheck) [the docs](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck) on this one.
## How do I tune resource limits?
If you don't place resource limits on your app it will assume it can use the entire capacity of the server it is on. This can cause issues such as OOM eerors for your entire swarm.
See the [Docker documentation](https://docs.docker.com/config/containers/resource_constraints/) to get into this topic and check the other recipes to see what other maintainers are doing.
## How do I enable A+ SSL ratings?
If you want to get the highest rating on SSL certs, you can use the following traefik labels which use a tweaked Traefik configuration.
```yaml
- "traefik.http.routers.traefik.tls.options=default@file"
- "traefik.http.routers.traefik.middlewares=security@file"
```
See [this PR](https://git.coopcloud.tech/coop-cloud/traefik/pulls/8/files) for the technical details
## How do I tweak secret generation length?
It is possible to tell `abra` which length it should generate secrets with from your recipe config.
You do this by adding a inline comment to the secret definition in the `.env.sample` / `.env` file.
Here are examples from the gitea recipe:
```
SECRET_INTERNAL_TOKEN_VERSION=v1 # length=105
SECRET_JWT_SECRET_VERSION=v1 # length=43
SECRET_SECRET_KEY_VERSION=v1 # length=64
```
When using this length specifier, `abra` will not use the "easy to remember
word" style generator but instead a string of characters to match the exact
length. This can be useful if you have to generate "key" style values instead
of passwords which admins have to type out in database shells.
## How are recipes added to the catalogue?
> This is so far a manual process which requires someone who's been added to the
> `coop-cloud` "Organisation" on https://git.coopcloud.tech. This is a temporary
> situation, we want to open out this process & also introduce some automation
> to support making thie process more convenient. Please nag us to move things
> along.
- Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
- Run `abra catalogue generate <recipe> -p`
- Run `cd ~/.abra/catalogue && make`
These minimal steps will publish a new recipe with no versions. You can also do
the [recipe release publishing dance](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-release-a-new-recipe-version)
which will then extend the `versions: [...]` section of the published JSON in the catalogue.
Recipes that are not included in the catalogue can still be deployed. It is not
required to add your recipes to the catalogue, but this will improve the
visibility for other co-op hosters & end-users.
For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/) if you want to add your recipe to the catalogue.
In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/coop-cloud/organising/issues/139).
## How do I configure backup/restore?
From the perspective of the recipe maintainer, backup/restore is just more
`deploy: ...` labels. Tools can read these labels and then perform the
backup/restore logic.
### Tools
Two of the current "blessed" options are
[`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) &
[`abra`](https://git.coopcloud.tech/coop-cloud/abra).
#### `backup-bot-two`
Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs.
#### `abra`
`abra` will read labels and store backups in `~/.abra/backups/...`.
### Backup
For backup, here are the labels & some examples:
- `backupbot.backup=true`: turn on backup logic
- `backupbot.backup.pre-hook=mysqldump -u root -pghost ghost --tab /var/lib/foo`: command to run before backing up
- `backupbot.backup.post-hook=rm -rf /var/lib/mysql-files/*`: command to run after backing up
- `backupbot.backup.path=/var/lib/foo,/var/lib/bar`: paths to back up
You place these on your recipe configuration and then tools can run backups.
### Restore
Restore, in this context means, "moving a compressed archive back to the
container backup paths". So, if you set
`backupbot.backup.path=/var/lib/foo,/var/lib/bar` and you have a backed up
archive, tooling will unzip files in the archive back to those paths.
In the case of restoring database tables, you can use the `pre-hook` &
`post-hook` commands to run the insertion logic.
## Can I override a service within a recipe?
You can use [this `docker-compose` trick](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files) to do this.
If you have a recipe that is using a `mysql` service and you'd like to use `postgresql` instead, you can create a `compose.psql.yml`!
An example of this is the [`selfoss`](https://git.coopcloud.tech/coop-cloud/selfoss) recipe. The default is `sqlite` but there is a `postgresql` compose configuration there too.

8
docs/maintainers/index.md
View File

@ -1,8 +0,0 @@
---
title: Maintainers guide
---
Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible.
- [New maintainers tutorial](/maintainers/tutorial): If you want to package a recipe and/or become a maintainer, start here :rocket:
- [Packaging handbook](/maintainers/handbook): One-stop shop for all you need to know to package recipes :package:

83
docs/maintainers/tutorial.md
View File

@ -1,83 +0,0 @@
---
title: New maintainers tutorial
---
## Package your first recipe
### Overview
Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.
The nice thing about packaging is that only one person has to do it and then we all benefit. We've seen that over time, the core of the configuration doesn't really change. New options and versions might come but the config remains quite stable. This is good since it means that your packaging work stays relevant and useful for other maintainers & operators as time goes on.
Depending on your familiarity with recipes, it might be worth reading [how a recipe is structured](/maintainers/handbook/#how-is-a-recipe-structured) and making clear you understand [what a recipe is](/glossary/#recipe) before continuing.
### Making a plan
The idea scenario is when the upstream project provides both the packaged image and a compose configuration which we can build from. If you're in luck, you'll typically find a `Dockerfile` and a `docker-compose.yml` file in the root of the upstream Git repository for the app.
- **Tired**: Write your own image and compose file from scratch
- **Wired**: Use someone else's image (& maybe compose file)
- **Inspired**: Upstream image, someone else's compose file
- **On fire**: Upstream image, upstream compose file
### Writing / adapting the `compose.yml`
Let's take a practical example, [Matomo web analytics](https://matomo.org/). We'll be making a Docker "swarm-mode" `compose.yml` file.
Luckily, Matomo already has an example compose file in their repository. Like a lot of compose files, it's intended for use with `docker-compose`, instead of "swarm mode", but it should be a good start.
First, let's create a directory with the files we need:
```
abra recipe new matomo
cd ~/.abra/recipes/matomo
```
Then, let's download and edit the `docker-compose.yml` file:
```
mkdir matomo && cd matomo
wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
```
Open the `compose.yml` in your favourite editor and have a gander &#129442;. There are a few things we're looking for, but some immediate changes could be:
1. Let's bump the version to `3.8`, to make sure we can use all the latest swarm coolness
2. We load environment variables separately via [`abra`](/abra/), so we'll strip out `env_file`
3. The `/var/www/html` volume definition on L21 is a bit overzealous; it means a copy of Matomo will be stored separately per app instance, which is a waste of space in most cases. We'll narrow it down according to the documentation. The developers have been nice enough to suggest `logs` and `config` volumes instead, which is a decent start
4. The MySQL passwords are sent as variables which is fine for basic use, but if we replace them with Docker secrets we can keep them out of our env files if we want to publish those more widely.
5. The MariaDB service doesn't need to be exposed to the internet, so we can define an `internal` network for it to communicate with Matomo.
6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
### Test deployment
!!! note "Running Co-op Cloud server required!"
The rest of this guide assumes you have a Co-op Cloud server going -- we'll use `swarm.example.com`, but replace it with your own server address. Head over to [the operators tutorial](/operators/tutorial) if you need help setting one up.
Now, we're ready to create a testing instance of Matomo:
```
abra app new matomo --secrets \
--domain matomo.swarm.example.com \
--server swarm.example.com
```
Depending on whether you defined any extra environment variables -- we didn't so
far, in this example -- you might want to run `abra app config swarm.example.com`
to check the configuration.
Otherwise, or once you've done that, go ahead and deploy the app:
```
abra app deploy swarm.example.com
```
Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
### Finishing up
You've probably got more questions, check out the [packaging handbook](/maintainers/handbook)!

13
docs/managed.md Normal file
View File

@ -0,0 +1,13 @@
---
title: Managed hosting
---
The Co-op Cloud is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) but you can still work with a co-operative or tech collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.
!!! danger "We're still working this out"
If you're a co-operative or a tech collective who wants to appear on this list, please [get in touch](/contact/)! We want to expand the number of service providers using the Co-op Cloud so that project is more widely available to end-users and organisations who can influence the direction and co-fund the development.
## Co-operatives
- [Autonomic](https://autonomic.zone) ([contact](mailto:helo@autonomic.zone))

21
docs/networking.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Docker Networking
---
!!! warning
Our understanding of Docker networking is probably wrong. We're working on it.
# Traefik networking
When a new Co-op Cloud instance is made, we make a "global" [overlay network](https://docs.docker.com/network/overlay/) which traefik sits on. This is the network that other apps use to speak to traefik and get traffic routed to them. Not every service in every app is also included in this network and hence not internet-facing.
# App networking
One service in an app, typically the one called `app`, sits on the "global" traefik network. This container is the one that should be publicy reachable on the internet. The other services in the app such as the database and caches should be not be publicly reachable or visible to other apps on the same instance.
To deal with this, we make an additional "internal" network for each app which is namespaced to that app. So, if you deploy a Wordpress instance called `my_wordpress_blog` then there will be a network called `my_wordpress_blog_internal` created. This allows all the services in an app to speak to each other but not be reachable on the public internet.
# Avoiding namespace conflicts
When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using Golang templating).

389
docs/operators/handbook.md
View File

@ -1,389 +0,0 @@
---
title: Operations handbook
---
## Understanding `~/.abra`
Co-op Cloud stores per-app configuration in the `$USER/.abra/servers` directory, on whichever machine you're running `abra` on (by default, your own work station). In other words, app configurations are grouped under their relevant server directory. This corresponds to the ordering of the output of `abra app ls`.
!!! question "What format do the `.env` files use?"
`.env` files use the same format as used by Docker (with the `env_file:` statement in a `docker-compose.yml` file, or the `--env-file` option to `docker run`) and `direnv`. There is no `export ...=...` required since `abra` will take care to thread the values into the recipe configuration at deploy time.
`abra` doesn't mind if `~/.abra/servers`, or any of its subdirectories, is a [symlink](https://en.wikipedia.org/wiki/Symlink), so you can keep your app definitions wherever you like!
```
mv ~/.abra/servers/ ~/coop-cloud
ln -s ~/coop-cloud ~/.abra/servers
```
You don't need to worry about `~/.abra/{vendor,catalogue,recipes,autocompletion}`, `abra` manages those automagically.
## Backing up `~/.abra`
Just make sure the `~/.abra/servers` is included in the configuration of your favourite backup tool. Because `~/.abra/servers` is a collection of plain-text files, it's easy to keep your backup configuration in a version control system (we use `git`, others would almost certainly work).
This is particularly recommended if you're collaborating with others, so that you can all run `abra app ...` commands without having to maintain your own separate, probably-conflicting, configuration files.
In the simple case where you only have one server configured with `abra`, or everyone in your team is using the same set of servers, you can version-control the whole `~/.abra/servers` directory:
```
cd ~/.abra/servers
git init
git add .
git commit -m "Initial import"
```
!!! warning "Test your revision-control self-discipline"
`abra` does not yet help keep your `~/.abra/server` configurations up-to-date! Make sure to run `git add` / `git commit` after making configuration changes, and `cd ~/.abra/servers && git pull` before running `abra app ...` commands. Patches to add some safety checks and auto-updates would be very welcome! 🙏
## Sharing `~/.abra`
In a more complex situation, where you're using Co-op Cloud to manage several servers, and you're collaborating with different people on different servers, you can set up **a separate repository for each subdirectory in `~/.abra/servers`**, or even a mixture of single-server and multi-server repositories:
```
ls -l ~/.abra/servers
# Example.com's own app configuration:
swarm.example.com -> /home/user/Example/coop-cloud-apps/swarm.example.com
# Configuration for one of Example.com's clients – part of the same repository:
swarm.client.com -> /home/user/Example/coop-cloud-apps/swarm.client.com
# A completely separate project, part of a different repository:
swarm.demonstration.com -> /home/user/Demonstration/coop-cloud-apps
```
To make setting up these symlinks easier, you might want to include a simple installer script in your configuration repositories.
Save this as `Makefile` in your repository:
```
# -s symlink, -f force creation, -F don't create symlink in the target dir
default:
@mkdir -p ~/.abra/servers/
@for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \
echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
done
```
This will set up symlinks from each directory in your repository to a correspondingly-named directory in `~/.abra/servers` – if your repository has a `swarm.example.com` directory, it'll be linked as `~/.abra/servers/swarm.example.com`.
Then, tell your collaborators (e.g. in the repository's `README.md`), to run `make` in their repository check-out.
!!! warning "You're on your own!"
As with the [simple repository set-up above](#backing-up-your-abra-configuration), `abra` doesn't yet help you update your version control system when you make changes, nor check version control to make sure you have the latest configuration. Make sure to `commit` and `push` after you make any configuration changes, and `pull` before running any `abra app ...` commands.
!!! question "Even more granularity?"
The plain-text, file-based configuration format means that you could even keep the configuration for different apps on the same server in different repositories, e.g. having `git.example.com` configuration in a separate repository to `wordpress.example.com`, using per-file symlinks.
We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage _any_ app in that swarm**.
### Migrating a server into a repository
Even if you've got your existing server configs in version control, by default, `abra server add` will define the server locally. To move it -- taking the example of `newserver.example.com`:
```
mv ~/.abra/servers/newserver.example.com ~/coop-cloud-apps/
cd ~/coop-cloud-apps
git add newserver.example.com
git commit
make link
```
## Running abra server side
If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local work station.
To install `abra` on the same server where you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local`.
```
abra server add --local
```
!!! note "Technical details"
This will tell `abra` to look at the Docker system running on the server, instead of a remote one (using the Docker internal `default` context). Once this is wired up, `abra` knows that the deployment target is the local server and not a remote one. This will be handle seamlessly for all other deployments on this server.
Make sure to back up your `~/.abra` directory on the server, or put it in version control, as well as other files you'd like to keep safe.
## Managing secret data
Co-op Cloud uses [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) to handle sensitive data, like database passwords and API keys, securely.
`abra` includes several commands to make it easier to manage secrets:
- `abra app secret generate <domain>`: to auto-generate app secrets
- `abra app secret insert <domain>`: to insert a single secret
- `abra app secret rm <domain>`: to remove secrets
### Secret versions
Docker secrets are immutable, which means that their values can't be changed after they're set. To accommodate this, Co-op Cloud uses the established convention of "secret versions". Every time you change (rotate) a secret, you will insert it as a new version. Because secret versions are managed per-instance by the people deploying their apps, secret versions are stored in the `.env` file for each app:
```
find -L ~/.abra/servers/ -name '*.env' -print0 | xargs -0 grep -h SECRET
OIDC_CLIENT_SECRET_VERSION=v1
RPC_SECRET_VERSION=v1
CLIENT_SECRET_VERSION=v1
...
```
If you try and add a secret version which already exists, Docker will helpfully complain:
```
abra app secret insert mywordpress.com db_password v1 foobar
Error response from daemon: rpc error: code = AlreadyExists desc = secret mywordpress_com_db_password_v1 already exists
```
By default, new app instances will look for `v1` secrets.
### Generating secrets automatically
You can generate secrets in one of two ways:
1. While running `abra app new <recipe>`, by passing `-S/--secrets`
2. At any point once an app instance is defined, by running `abra app secret generate <domain> ...` (see `abra app secret generate -h` for more)
### Inserting secrets manually
For third-party API tokens, like OAuth client secrets, or keys for services like Mailgun, you will be storing values you already have as the appropriately-named Docker secrets. `abra` provides a convenient interface to the underlying `docker secret create` command:
```
abra app secret insert <domain> db_password v2 "your-secret-value-here"
```
### Rotating a secret
So, given how [secret versions](/operators/handbook/#secret-versions) work, here's how you change a secret:
1. Find out the current version number of the secret, e.g. by running `abra app config <domain>`, and choose a new one. Let's assume it's currently `v1`, so by convention the new secret will be `v2`
2. Generate or insert the new secret: `abra app secret generate <domain> db_password v2` or `abra app secret insert <domain> db_password v2 "foobar"`
3. Edit the app configuration to change which secret version the app will use: `abra app config <domain>`
4. Re-reploy the app with the new secret version: `abra app deploy <domain>`
### Storing secrets in `pass`
The Co-op Cloud authors use the [UNIX `pass` tool][pass] to share sensitive data, including Co-op Cloud secrets, and `abra app secret ...` commands include a `--pass` option to automatically manage generated / inserted secrets:
```
# Store generated secrets in `pass`:
abra app new wordpress --secrets --pass
abra app secret generate mywordpress.com --all --pass
# Store inserted secret in `pass`:
abra app secret insert mywordpress.com db_password v2 --pass
# Remove secrets from Docker, and `pass`:
abra app secret rm mywordpress.com --all --pass
```
This functionality currently relies on our specific `pass` storage conventions; patches to make that configurable are very welcome!
## Networking
!!! note "So dark the con of Docker Networking"
Our understanding of Docker networking is probably wrong. We're working on it. Plz send halp :pray:
### Traefik networking
[Traefik](https://doc.traefik.io/traefik/) is our core web proxy, all traffic on a Co-op Cloud deployment goes through a running Traefik container. When setting up a new Co-op Cloud delpyment, `abra` creates a "global" [overlay network](https://docs.docker.com/network/overlay/) which traefik is hooked up to. This is the network that other apps use to speak to traefik and get traffic routed to them. Not every service in every app is also included in this network and hence not internet-facing (by convention, we name this network `internal`, see more below).
### App networking
By convention, the main `app` service is wired up to the "global" traefik overlay network. This container is the one that should be publicy reachable on the internet. The other services in the app such as the database and caches should be not be publicly reachable or visible to other apps on the same instance.
To deal with this, we make an additional "internal" network for each app which is namespaced to that app. So, if you deploy a Wordpress instance called `my_wordpress_blog` then there will be a network called `my_wordpress_blog_internal` created. This allows all the services in an app to speak to each other but not be reachable on the public internet.
## Multiple apps on the same domain?
At time of writing (Jan 2022), we think there is a limitation in our design which doesn't support multiple apps sharing the same domain (e.g. `example.com/app1/` & `example.com/app2/`). `abra` treats each domain as unique and as the singler reference for a single app.
This may be possible to overcome if someone really needs it, we encourage people to investigate. We've found that often, there are limitations in the actual software which don't support this anyway and several of the current operators simply use a new domain per app.
## Validating `abra` binary checksums
You can download `abra` yourself from the [releases page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the `checksums.txt` file.
```bash
grep $(sha256sum abra_[version]_[platform]) checksums.txt > /dev/null && echo "checksum OK"
```
If "checksum OK" appears in your terminal - you're good to go!
Otherwise, you have downloaded a corrupted file.
## Creating a new server
`abra server new` can create servers if you have an account with a supported 3rd party integration. We currently support [Servers.coop](https://servers.coop) & [Hetzner](https://hetzner.com). The process of creating a new server usually goes like this:
1. Create an account with a server hosting provider
2. Generate an API client key which you'll give to `abra`
3. Run `abra server new` & fill in the values
`abra` supports creating, listing and removing servers if the 3rd party integration supports it.
If you want to teach `abra` how to support your favourite server hosting provider, we'd glady accept patches.
## How do I bootstrap a server for running Co-op Cloud apps?
The requirements are:
1. Docker installed
1. User in Docker user group
1. Swarm mode initialised
1. Proxy network created
```
# docker install convenience script
wget -O- https://get.docker.com | bash
# add user to docker group
usermod -aG docker $USER
# setup swarm
docker swarm init
docker network create -d overlay proxy
```
`abra` will do this for you when you run `abra server add --provision`.
## Managing DNS entries
`abra record ...` can help you manage your DNS entries if you have an account with a supported 3rd party provider. We currently support [Gandi](https://gandi.net). The process of managing DNS with `abra` usually goes like this:
1. Create an account with a DNS service provider
2. Generate an API client key which you'll give to `abra`
3. Run `abra record ls` to check everything works
`abra` supports creating, listing and removing DNS entries if the 3rd party integration supports it.
If you want to teach `abra` how to support your favourite server hosting provider, we'd glady accept patches.
## How do I persist container logs after they go away?
This is a big topic but in general, if you're looking for something quick & easy, you can use the [journald logging driver](https://docs.docker.com/config/containers/logging/journald/). This will hook the container logs into systemd which can handle persistent log collection & managing log file size.
You need to add the following to your `/etc/docker/daemon.json` file on the server:
```json
{
"log-driver": "journald",
"log-opts": {
"labels":"com.docker.swarm.service.name"
}
}
```
And for log size management, edit `/etc/systemd/journald.conf`:
```
[Journal]
Storage=persistent
SystemMaxUse=5G
MaxFileSec=1month
```
Tne restart `docker` & `journald`:
```
systemctl restart docker
systemctl restart systemd-journald
```
Now when you use `docker service logs` or `abra app logs`, it will read from the systemd journald logger seamlessly! Some useful `journalctl` commands are as follows, if you're doing some more fine grained logs investigation:
- `journalctl -f`
- `journalctl CONTAINER_NAME=my_git_com_app.1.jxn9r85el63pdz42ykjnmh792 -f`
- `journalctl COM_DOCKER_SWARM_SERVICE_NAME=my_git_com_app --since="2020-09-18 13:00:00" --until="2020-09-18 13:01:00"`
- `journalctl CONTAINER_ID=$(docker ps -qf name=my_git_com_app) -f`
Also, for more system wide analysis stuff:
- `journalctl --disk-usage`
- `du -sh /var/log/journal/*`
- `man journalctl` / `man systemd-journald` / `man journald.conf`
## How do I specify a custom user/port for SSH connections with `abra`?
`abra` uses plain 'ol SSH under the hood and aims to make use of your existing SSH configurations in `~/.ssh/config` and interfaces with your running `ssh-agent` for password protected secret key files.
The `server add` command listed above assumes that that you make SSH connections on port 22 using your current username. If that is not he case, pass the new values as positional arguments. See `abra server add -h` for more on this.
```bash
abra server add <domain> <user> <port> -p
```
Running `server add` with `-d/--debug` should help you debug what is going on under the hood. It's best to take a moment to read [this troubleshooting entry](/abra/trouble/#ssh-connection-issues) if you're running into SSH connection issues with `abra`.
## How do I attach to a running container?
If you need to run a command within a running container you can use `abra app run <domain> <service> <command>`. For example, you could run `abra app run cloud.lumbung.space app bash` to open a new bash terminal session inside your remote container.
## How do I attach on a non-running container?
If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again.
## Can I run Co-op Cloud on ARM?
`@Mayel`:
> FYI I've been running on ARM for a while with no troubles (as long as images
> used support it of course, `abra` doesn't work yet!) 😀 ... in cases where I
> couldn't find a multiarch image I simply have eg. image: ${DB_DOCKER_IMAGE}
> in the docker-compose and set that to a compatible image in the env config
> ... there was really nothing to it, apart from making sure to use multiarch
> or arm images
See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for more.
## How do I backup/restore my app?
If you're app [supports backup/restore](/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/coop-cloud/abra).
With `abra`, you can simply run `abra app backup ...` & `abra app restore ...`.
Pass `-h` for more information on the specific flags & arguments.
## How do I take a manual database backup?
MySQL / MariaDB:
```
abra app run foo.bar.com db mysqldump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
```
Postgres:
```
abra app run foo.bar.com db pg_dump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
```
If you get errors about database access:
- Make sure you've specified the right database user (`root` above) and db name
- If you have a database password set, you might need to load it from a secret,
something like this:
```
abra app run foo.bar.com db bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
```
## Can I deploy a recipe without `abra`?
Yes! It's a design goal to keep the recipes not dependent on `abra` or any
single tool that we develop. This means the configurationc commons can still be
useful beyond this project. You can deploy a recipe with standard commands like
so:
```
set -a
source example.com.env
cd ~/.abra/recipes/myrecipe
docker stack deploy -c compose.yml example_com
```
`abra` makes all of this more cenvenient but other tooling could follow this
approach.

8
docs/operators/index.md
View File

@ -1,8 +0,0 @@
---
title: Operators Guide
---
Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly. Operators are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:
- [New operators tutorial](/operators/tutorial): If you want to become an operator, start here :rocket:
- [Operations handbook](/operators/handbook): One-stop shop for all you need to know to manage a deployment :ribbon:

299
docs/operators/tutorial.md
View File

@ -1,299 +0,0 @@
---
title: New operators tutorial
---
## The moving parts
Co-op Cloud is made up of a few simple, composable pieces. The system does not rely on any one specific implementation: each part may be replaced and/or extended as needed.
We want to build a resilient and long-term sustainable project and that means allowing for different implementations, open formats and a diverse project organisation.
Here are the main technical concepts listed below, once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app).
### Libre software apps
Libre software apps are tools, websites & software clients that you may already use in your daily life: [Nextcloud], [Jitsi], [Mediawiki], [Rocket.chat] and [many more]!
These are tools that are created by volunteer communities who use [free software licenses] in order to build up the public software commons and offer more digital alternatives to [proprietary systems].
The communities who develop these softwares also publish them using [containers]. For example, here is the [Nextcloud hub.docker.com account] which allows end-users to quickly deploy a new Nextcloud instance.
There is a growing consensus in the free software community that containers are a useful and time saving format for distribution.
!!! question "Why did you choose to use containers?"
Learn more [in the FAQ section](/intro/faq/#why-containers).
[nextcloud]: https://nextcloud.com
[jitsi]: https://jitsi.org
[mediawiki]: https://mediawiki.org
[rocket.chat]: https://rocket.chat
[many more]: /recipes/
[free software licenses]: https://www.gnu.org/philosophy/free-sw.html
[nextcloud hub.docker.com account]: https://hub.docker.com/_/nextcloud
[proprietary systems]: https://en.wikipedia.org/wiki/Proprietary_software
[containers]: https://www.docker.com/resources/what-container
### The recipe packaging format
However, just having a container of an app is often not enough. The work required to deploy that app in a "production ready" setup is still too time intensive and often involves a duplication of effort.
Each service provider needs to deal with the same problems: stable versioning, backup plan, secret management, upgrade plan, monitoring and the list goes on.
Individual free software projects can't take on all this responsibility. They provide the containers as is, in a secure and ready-to-go manner but it is up to service providers to worry about how the app is deployed.
Therefore, Co-op Cloud proposes a packaging format, which we refer to as a recipe, that describes the entire production state of the app in a single place. This format uses the existing [standards based compose specification].
This is a file format which is most commonly used by the [Docker compose] tool but Co-op Cloud **does not** require the use of Docker compose itself. Furthermore, as described below, we also don't rely on the actual Docker CLI itself either. We do however use a lot of the underlying libraries.
!!! question "Why did you choose to use the compose specificiation?"
Learn more [in the FAQ section](/intro/faq/#why-use-the-compose-specification).
[Each recipe] that Co-op cloud provides is described using the compose specification and makes use of the upstream project published container when possible (sometimes they don't publish one!).
This is the core of our approach to working with the ecosystem of free software communities. We want to maximise the chances of sharing work, knowledge and build solidarity through concrete co-operation.
[standards based compose specification]: https://compose-spec.io
[docker compose]: https://docs.docker.com/compose/
[each recipe]: /recipes/
### Container orchestrator
Once we have our app packaged as a recipe, we need a deployment environment (e.g. a server & something to keep the containers running). Production deployments are typically expected to support a number of features which give hosters and end-users guarantees for stability.
The Co-op cloud makes use of [Docker swarm] as a deployment environment. It offers an approriate feature set which allows us to support zero-down time upgrades, seamless app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design.
!!! question "Why did you choose to use Docker Swarm?"
Learn more [in the FAQ section](/intro/faq/#why-docker-swarm).
[docker swarm]: https://docs.docker.com/engine/swarm/
### Command-line tool
Finally, we need a tool to read the recipe package format and actually deploy the app. For this, we have developed and published the [abra] command-line tool.
`abra` aims at providing a simple command-line interface for managing your own Co-op Cloud. You can bootstrap machines with the required tools, create new apps and deploy them. `abra` is written in [Go](https://go.dev/) and uses a lot of the libraries that the `docker` and `docker-compose` CLIs use but does not rely on those interfaces directly.
`abra` is our flagship command-line client but it does not need to be the only client. `abra` was designed in such a way that it complements a workflow which can still be done completely manually. If Co-op Cloud goes away tomorrow, our configuration commons would still be useful and usable.
[abra]: /abra/
## Deploy your first app
In order to deploy an app you need two things:
1. a server with SSH access and a public IP address
2. a domain name pointing to that server
The tutorial tries to help you make choices about which server and which DNS setup you need to run a Co-op Cloud deployment but it does not go into great depth about how to set up a new server.
!!! question "Can `abra` help automate this?"
`abra` can help bootstrap new servers & configure DNS records for you. We'll skip that for now since we're just getting started. See the [operators handbook](/operators/handbook) for more on these topics after you finish the tutorial.
### Server setup
Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html). You may also be interested in this [FAQ entry](/intro/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
Most Co-op Cloud deployments have been run on Debian machines so far. Some experiments have been done on single board computers & servers with low resource capacities.
You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy ([Traefik](https://traefik.io)) keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
`abra` has support for both creating servers (`abra server new`) & provisioning them (passing `--provision` to `abra server add`) but those are more advanced automation options which are covered in the [handbook](/operators/handbook). For this tutorial, we'll focus on the basics. Assuming you've managed to create a testing VPS with some `$hosting_provider`, you'll need to install Docker, add your user to the Docker group & setup swarm mode:
```
# docker install convenience script
wget -O- https://get.docker.com | bash
# add user to docker group
sudo usermod -aG docker $USER
# setup swarm
docker swarm init
docker network create -d overlay proxy
```
!!! question "Do you support multiple web proxies?"
We do not know if it is feasible and convenient to set things up on an existing server with another web proxy which uses ports `:80` & `:443`. We'd happily receive reports and documentation on how to do this if you manage to set it up!
### DNS setup
You'll need two A records, one to point to the server itself and another to support sub-domains for the apps. You can then support an app hosted on your root domain (e.g. `example.com`) and other apps on sub-domains (e.g. `foo.example.com`, `bar.example.com`).
Your entries in your DNS provider setup might look like the following.
@ 1800 IN A 116.203.211.204
*. 1800 IN A 116.203.211.204
Where `116.203.211.204` can be replaced with the IP address of your server.
!!! question "How do I know my DNS is working?"
You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working.
### Command-line setup
#### Install `abra`
Now we can install [`abra`](/abra) locally on your machine and hook it up to your server.
We support a script-based installation method (script source [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer)):
```bash
curl https://install.abra.coopcloud.tech | bash
```
The installer will verify the downloaded binary checksum. You may need to add the `~/.local/bin/` directory with your `$PATH` in order to run the executable. You can validate that everything is in working order by listing the default help output:
```bash
export PATH=$PATH:$HOME/.local/bin
abra -h # check it works
```
If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this.
!!! question "Can I install `abra` on my server?"
Yes, this is possible, see [this handbook entry](/operators/handbook/#running-abra-server-side) for more. The instructions for setup are a little different however.
#### Add your server
Now you can connect `abra` with your server. You need to have a working SSH configuration before you can do this. That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:.
```bash
abra server add <server-domain> -p
```
The `-p` or `--provision` flag means that `abra` will install Docker and initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server. If you've already followed the steps in [the server setup](/operators/tutorial/#server-setup) step, then `abra` should not need to do any work.
It is important to note that `<domain>` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.
You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance.
`abra` should now register this server as managed in your server listing:
```
abra server ls
```
!!! warning "Beware of SSH dragons"
`abra` uses plain 'ol SSH under the hood and aims to make use of your existing SSH configurations in `~/.ssh/config` and interfaces with your running `ssh-agent` for password protected secret key files.
The `server add` command listed above assumes that that you make SSH connections on port 22 using your current username. If that is not he case, pass the new values as positional arguments. See `abra server add -h` for more on this.
abra server add <domain> <user> <port> -p
Running `server add` with `-d/--debug` should help you debug what is going on under the hood. It's best to take a moment to read [this troubleshooting entry](/abra/trouble/#ssh-connection-issues) if you're running into SSH connection issues with `abra`.
!!! question "How do I share my configs in `~/.abra`?"
It's possible and quite easy, see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration) for more.
### Web proxy setup
In order to have your Co-op cloud deployment serve the public internet, we need to install the core web proxy, [Traefik](https://doc.traefik.io/traefik/).
Traefik is the main entrypoint for all web requests (e.g. like NGINX) and supports automatic SSL certificate configuration and other quality-of-life features which make deploying libre apps more enjoyable.
To get started, you'll need to create a new app:
```bash
abra app new traefik
```
Choose your newly registered server and specify a domain name.
You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value. You can do that by running `abra app config`:
```bash
abra app config <traefik-domain>
```
Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
Now it is time to deploy:
```
abra app deploy <traefik-domain>
```
### Deploy Nextcloud
And now we can deploy apps. Let's create a new Nextcloud app.
```bash
abra app new nextcloud -S
```
The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password.
!!! warning "Beware of password dragons"
Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system.
Then we can deploy Nextcloud:
```bash
abra app deploy <nextcloud-domain>
```
`abra app deploy` will wait nearly a minute for an app to deploy until it times out and shows some helpful commands for how to debug what is going on. If things don't come up in time, try running the following:
```
abra app ps -w <nextcloud-domain> # status check
abra app logs <nextcloud-domain> # logs trailing
abra app errors -w <nextcloud-domain> # error catcher
```
Your new `traefik` instance will detect that a new app is coming up and generate SSL certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<netcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
### Upgrade Nextcloud
To upgrade an app manually to the newest available version run:
```bash
abra app upgrade <nextcloud-domain>
```
### Automatic Upgrades
`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments.
To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades.
The following script will configure ssmtp for email notifications and setup a cronjob.
This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
```bash
apt install ssmtp
cat > /etc/ssmtp/ssmtp.conf << EOF
mailhub=$MAIL_SERVER:587
hostname=$MAIL_DOMAIN
AuthUser=$USER
AuthPass=$PASSWORD
FromLineOverride=yes
UseSTARTTLS=yes
EOF
cat > /etc/cron.d/abra_updater << EOF
MAILTO=admin@example.com
MAILFROM=noreply@example.com
0 6 * * * root ~/kadabra notify --major
30 4 * * * root ~/kadabra upgrade --all
EOF
```
## Finishing up
Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.
If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.

37
docs/organisers/handbook.md
View File

@ -1,37 +0,0 @@
---
title: Organising handbook
---
## Where do I find "the community"?
The main place is the [Matrix community chat channels](/intro/contact/#matrix). You'll find a number of folks who are actively interested in the project and/or using `abra` and some of our recipes. Furthermore, Matrix has an excellent network of Cool People :tm: and in practice we've e-met a lot of groups who are interested in Co-op Cloud.
## Onboarding new project members
We still haven't worked this out. We're working on it.
## Gathering new case studies
We try to gather as many "case studies" as possible, stories & concrete examples of Co-op Cloud being used For Good :tm: See [coopcloud.tech](https://coopcloud.tech) for our existing examples. These studies help people identify what the purpose of the project is for.
## Monthly updates
We have decided we'll try to do monthly progress updates. These will be published on the Co-op Cloud blog. It's a pretty loose format and we're basically just copy/pasta'ing things to a public pad during the month: ["This month in Co-op Cloud"](https://pad.autonomic.zone/YHKn4vHORmS6wjN1t2zi5A?both). Feel free to add your items to the monthly agenda and they will be included! All the previous posts can be seen [here](https://coopcloud.tech/blog/).
## Kite Flying Hours
The "Kite Flying Hour" is a weekly public moment where anyone can "drop by" into a Jitsi call and ask/do/propose whatever and meet some people who are currently working on the project. We haven't worked it all out but our process for now is the following.
Someone from Autonomic will volunteer to be present and talk about the project for an hour weekly from 15:00 CEST - 16:00 CEST. We announce the hour via our socials: A [pinned toot](https://social.coop/web/statuses/106528094828958420) on [`@coopcloud@social.coop`](https://social.coop/@coopcloud) and a post to the `#coopcloud:autonomic.zone` room.
Here is some invitation boilerplate which you can use:
> Hey folks, you're all warmly invited to the Co-op Cloud Kite Flying Hour at `$X_TIME` `$Y_TZ` `$Z_DATE` over in [meet.jit.si/CoopCloudKiteFlyingHour](https://meet.jit.si/CoopCloudKiteFlyingHour)!
>
> Inspired by exquisite childhood memories of [flying kites, eating popsicles and looking at clouds](https://norwichhistory.org/norwich-a-z-j-is-for-jigsaw/), it's an open hour to come hang out online and discuss/co-work/lurk/etc. around the [Co-op Cloud](https://coopcloud.tech/) project.
>
> There are no "stupid questions"! It's a space to inquire, be curious and have a good time and get to know each other.
>
> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/LqotfSJJRj69RcTtWmr7iw). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
>
> Hope to see you there! ☁️ 🌞 🖥️

9
docs/organisers/index.md
View File

@ -1,9 +0,0 @@
---
title: Organisers Guide
---
Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things up come up in the community chats, etc. It's important work.
We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:
- [Organising handbook](/organisers/handbook): One-stop shop for all you need to know to organise in the community :sparkles:

64
docs/overview.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Technical overview
---
The Co-op Cloud is made up of a few simple, composable pieces. The system does not rely on any one specific implementation: each part may be replaced and extended as needed.
- [Libre software apps](#libre-software-apps)
- [The packaging format](#the-packaging-format)
- [Container orchestrator](#container-orchestrator)
- [Command-line tool](#command-line-tool)
## Libre software apps
Applications that you may already use in your daily life: [Nextcloud], [Jitsi], [Mediawiki], [Rocket.chat] and [many more]! These are tools that are created by volunteer communities who use [free software licenses] in order to build up the public software commons and offer more digital alternatives.
The communities who develop these softwares also publish them using containers. For example, here is the [Nextcloud hub.docker.com account] which allows end-users to quickly deploy a new Nextcloud instance.
Learn more about why we use containers [in the FAQ section](/faq/#why-containers).
[nextcloud]: https://nextcloud.com
[jitsi]: https://jitsi.org
[mediawiki]: https://mediawiki.org
[rocket.chat]: https://rocket.chat
[many more]: /apps/
[free software licenses]: https://www.gnu.org/philosophy/free-sw.html
[nextcloud hub.docker.com account]: https://hub.docker.com/_/nextcloud
## The packaging format
The work required to take a new instance of an application and make it production ready is still too time intensive and often involves a duplication of effort. Each service provider needs to deal with the same problems: stable versioning, backup plan, secret management, upgrade plan, monitoring and the list goes on.
Therefore, the Co-op Cloud proposes a packaging format which describes the entire production state of the application in a single place. This format uses the existing [standards based compose specification]. This is a file format which is most commonly used by the [Docker compose] tool but Co-op Cloud **does not** require the use of Docker compose itself.
[Each application] that the Co-op cloud provides is described using the compose specification and makes use of the upstream project published container.
Learn more about why we use the compose specification [in the FAQ section](/faq/#why-use-the-compose-specification).
[standards based compose specification]: https://compose-spec.io
[docker compose]: https://docs.docker.com/compose/
[each application]: /apps/
## Container orchestrator
Once we have our application packaged, we need a deployment environment. Production deployments are typically expected to support a number of features which give hosters and end-users guarantees for uptime, stability and scale.
The Co-op cloud makes use of [Docker swarm] as a deployment environment. It offers an approriate feature set which allows us to support zero-down time upgrades, seamless application rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design.
Learn more about why we use Docker swarm [in the FAQ section](/faq/#why-docker-swarm).
[docker swarm]: https://docs.docker.com/engine/swarm/
## Command-line tool
Finally, with an application and an application environment, we need a tool to read that package format and actually deploy it to the environment. For this, we have developed and published the [abra] command-line tool.
Abra aims at providing a simple command-line interface for managing your own co-op cloud. You can bootstrap machines with the required tools, create new applications, deploy them, back them up, restore them and so on.
[abra]: https://git.autonomic.zone/coop-cloud/abra
## Next steps
Now that you've got an overview, it is time to [deploy your first application].
[deploy your first application]: /deploy/

106
docs/recipe-maintainer-guide.md Normal file
View File

@ -0,0 +1,106 @@
---
title: Recipe maintainer guide
---
## Package your first recipe
Let's take as an example, [Matomo web analytics](https://matomo.org/).
We'll be making a Docker "swarm-mode" `compose.yml` file.
- Tired: Write your own image and compose file
- Wired: Use someone else's image (& maybe compose file)
- Inspired: Upstream image, someone else's compose file
- On fire: Upstream compose file
I'm feeling lazy so, luckily for me, Matomo already has an example compose file in their repository.
Like a lot of compose files, it's intended for use with `docker-compose`, instead of "swarm mode", but it should be a good start.
First, let's create a directory with the files we need:
```
abra recipe new matomo
cd ~/.abra/apps/matomo
```
Then, let's download and edit the `docker-compose.yml` file:
```
mkdir matomo && cd matomo
wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
```
Open the `compose.yml` in your favourite editor and have a gander &#129442;. There are a few things we're looking for -- full list to come -- but some immediate changes could be:
1. Let's bump the version to `3.8`, to make sure we can use all the latest swarm coolness
2. We load environment variables separately via [abra](/overview/#command-line-tool), so we'll strip out `env_file`.
3. The `/var/www/html` volume definition on L21 is a bit overzealous; it means a copy of Matomo will be stored separately per app instance, which is a waste of space in most cases. We'll narrow it down according to the documentation -- here, the developers have been nice enough to suggest `logs` and `config` volumes instead, which is a decent start
4. The MySQL passwords are sent as variables which is fine for basic use, but if we replace them with Docker secrets we can keep them out of our env files if we want to publish those more widely.
5. The MariaDB service doesn't need to be exposed to the internet, so we can define an `internal` network for it to communicate with Matomo.
6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
!!! note "Running Co-op Cloud server required!"
The rest of this guide assumes you have a Co-op Cloud server going -- we'll use `swarm.example.com`, but replace it with your own server address.
Head over to [the deployment guide](./deploy.md) if you need help setting one up.
Now, we're ready to create a testing instance of Matomo:
```
abra app new matomo --secrets \
--domain matomo.swarm.example.com \
--server swarm.example.com \
--app-name mygreatapp
```
Depending on whether you defined any extra environment variables -- we didn't so
far, in this example -- you might want to run `abra app mygreatapp config` to
check the configuration.
Otherwise, or once you've done that, go ahead and deploy the app:
```
abra app mygreatapp deploy
```
Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables -- if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
## How recipes are versioned
> We are still working on stabilising this workflow
We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
The Gitea project maintains a version, e.g. `1.14.3`. This version uses the [semver](https://semver.org) strategy for communicating what type of changes are included in each version, i.e., if there is a breaking change, Gitea will release a new version as `2.0.0`.
However, there are other types of changes that can happen for a recipe. Perhaps the database image gets a breaking update or the actual recipe configuration changes some environment variable. This can mean that end-users of the recipe need to do some work to make sure their updates will deploy successfully.
Therefore, we maintain an additional version part, in front of the project version. So, the first release of the Gitea recipe in the Co-op Cloud project has the version of `1.0.0+1.14.3-rootless`. This `x.y.z+` is the version part that the recipe maintainer manages. If a new available Gitea version comes out as `1.15-rootless` then the recipe maintainer will publish `1.1.0+1.15-rootless` as this is a backwards compatible update, following semantic versioning.
In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3-rootless` to `1.15.3-rootless`, we still publish `1.1.0+1.15.3-rootless` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
The commands uses for dealing with this logic in `abra` are:
- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
- `abra recipe tag`: publish a git tag for the recipe repo
- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
## How to publish a new recipe version
!!! warning
Due to [a limitation](https://git.coopcloud.tech/coop-cloud/organising/issues/185) in the Git library we're using in `abra`, when tagging new releases, you **must** use annotated git tags (i.e. `git tag -a`) or `abra` won't be able to parse them correctly. On the up side, it is probably better to leave a message with your new Git tag anyway. So maybe this is just "best practice" ;)
> This process is very much still a work in progress...
- `abra recipe upgrade keycloak`
- `abra recipe sync keycloak "1.0.0+13.0.1"`
- `abra recipe release -c --cm "chore: first release" -t "first release" --push`
## Style guide
- Please don't use `&image` YAML repeat anchors on the `image: ...` key because our `recipe release` logic does not handle it (see [#172](https://git.autonomic.zone/coop-cloud/abra/issues/172))

50
docs/recipe-structure.md Normal file
View File

@ -0,0 +1,50 @@
---
title: Recipe structure
---
A recipe is a git repository that contains instructions for creating stacks that abra can read and interpret. You'll see a couple of files there:
- [compose.yml](#composeyml) (required!)
- [.env.sample](#envsample) (required!)
- [abra.sh](#abrash)
- [entrypoint.sh](#entrypointsh)
- [other compose files](#other-compose-files)
- [other files](#other-files)
## compose.yml
this is a [compose specification](https://compose-spec.io/) compliant file that contains a list of:
- services
- secrets
- networks
- volumes
- configs
that describe what is needed to run a stack. Whenever you deploy an app, abra reads this file to cook the stack.
## .env.sample
this file is a skeleton for environmental variables that should be adjusted by the user. Examples include: domain or php extention list. Whenever you create a new app with `abra app new` this file gets copied to the ~/.abra/servers/server-domain/app-name.env and when you run `abra app config` you're editing this file.
## abra.sh
`abra.sh` provides shell functions for running non-standard deploy, restore, rollback, backup and upgrade. This is only needed for some packages (such as nextcloud or wordpress)
## entrypoint.sh
after docker creates the filesystem and copies files into a new container it runs what's called an entrypoint. This is usually a shell script that exports some variables and runs the application. Sometimes the vendor entrypoint doesn't do everything that we need it to do. In that case you can write your own entrypoint, do whatever you need to do and then run the vendor entrypoint. For a simple example check [entrypoint.sh for croc](https://git.coopcloud.tech/coop-cloud/croc/src/commit/2f06e8aac52a3850d527434a26de0a242bea0c79/entrypoint.sh). In this case, croc needs the password to be exported as an environmental variable called `CROC_PASS`, and that is exactly what the entrypoint does before running vendor entrypoint. If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml.
## other compose files
i.e. compose.smtp.yml. These are used to provide non-essential functionality such as (registration) e-mails or single sign on.
## other files
if you look at compose.yml (or compose.\*.yml) and see a `configs` section, that means this compose file is putting files in the container. This might be used for changing default (vendor) configuration, such as this [fpm-tune.ini file](https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/28425b6138603067021757de28c639ad464e9cf8/fpm-tune.ini) used to adjust php-fpm.

83
docs/recipes/index.md
View File

@ -1,83 +0,0 @@
---
title: Recipes
---
!!! note "Unsure of what a "recipe" is exactly?"
Not to worry, we've got you covered, check out our [glossary page entry](/glossary#recipe).
## Catalogue
The recipe catalogue is a web interface for exploring
what kind of configurations we have available in the project and therefore what apps can be deployed.
It aims to be a helpful place to understand the status of apps, who is taking care of the configs and who is maintaining deployed instances of which app.
The recipe catalogue is available on [recipes.coopcloud.tech](https://recipes.coopcloud.tech/).
## Status / features / scoring
Each recipe README has a "metadata" section, to help communicate the overall status of the recipe, and which features are supported. Here's an example, from [the Wordpress recipe](https://git.coopcloud.tech/coop-cloud/wordpress/):
```
<!-- metadata -->
* **Category**: Apps
* **Status**: 3, stable
* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream
* **Healthcheck**: Yes
* **Backups**: Yes
* **Email**: 3
* **Tests**: 2
* **SSO**: No
<!-- endmetadata -->
```
Currently, recipe maintainers need to update the scores in this section manually. The specific meanings of the scores are:
### Status (overall score)
- 5: everything in 4 + Single-Sign-On
- 4: upstream image, backups, email, healthcheck, integration testing
- 3: upstream image, missing 1-2 items from 4
- 2: missing 3-4 items from 4 or no upstream image
- 1: alpha
### Image
- 4: official upstream image
- 3: semi-official / actively-maintained image
- 2: 3rd-party image
- 1: our own custom image
### Email
- 3: automatic (using environment variables)
- 2: mostly automatic
- 1: manual
- 0: none
- N/A: app doesn't send email
### CI
- 3: as 2, plus healthcheck
- 2: auto secrets + networks
- 1: basic deployment using `stack-ssh-deploy`, manual secrets + networks
- 0: none
### Single-Sign-On
- 3: automatic (using environment variables)
- 2: mostly automatic
- 1: manual
- 0: none
- N/A: app doesn't support SSO
## Wishlist
If you'd like to see a new recipe packaged, make a request on the [recipes-wishlist](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker.
We've seen nice things happen when the requesters are also willing to take an active role in testing the new recipe. Teaming up with whoever volunteers to help do the packaging is best.
If no one is around to help, you can always take a run at it yourself, we have [a section](/maintainers/) ready to help you on your way.

5
docs/rollback.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Roll an app back to a previous version
---
TODO.

5
docs/scale.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Scale an app up to handle more traffic
---
TODO.

109
docs/secrets.md Normal file
View File

@ -0,0 +1,109 @@
---
title: Managing secret data
---
# Managing secret data
Co-op Cloud uses [Docker Secrets] to handle sensitive data, like database passwords and API keys, securely:
```
DOCKER_CONTEXT=swarm.example.com docker secret ls
example_mediawiki_db_password_v1
example_wordpress_db_password_v1
```
`abra` includes several commands to make it easier to manage secrets:
- `abra app <app> secret generate` -- to auto-generate a single secret, or all secrets defined by the app, and store them in the Docker Swarm store,
- `abra app <app> secret insert` -- to insert a single secret value from the Docker Swarm store,
- `abra app <app> secret delete` -- to remove a single secret, or all secrets defined in the app, from the Docker Swarm store.
<a id="versions"></a>
## Secret versions
You will notice `v1` in the example secret names above: like Docker Configs, Docker Secrets are [immutable], which means that their values can't be changed after they're set. To accommodate this, Co-op Cloud uses the established convention of "secret versions". Every time you change (rotate) a secret, you will insert it as a new version.
Because secret versions are managed per-instance by the people deploying their apps, secret versions are stored in the `.env` file for each app:
```
find -L ~/.abra/servers/ -name '*.env' -print0 | xargs -0 grep -h SECRET
OIDC_CLIENT_SECRET_VERSION=v1
RPC_SECRET_VERSION=v1
CLIENT_SECRET_VERSION=v1
...
```
If you try and add a secret version which already exists, Docker will helpfully complain:
```
abra app example_wordpress secret insert db_password v1 foobar
Error response from daemon: rpc error: code = AlreadyExists desc = secret example_wordpress_db_password_v1 already exists
```
By default, new app instances will look for `v1` secrets.
## Generating secrets automatically
You can generate secrets in one of two ways:
1. While running `abra app new <type>`, by passing `--secrets`
2. At any point once an app instance is defined, by running `abra app <app> secret generate ...` (see `abra help secret generate` for full options)
!!! note "How are secrets generated?"
Depending on how the app is configured, you will require the `pwqgen` (from `passwdqc`) and `pwgen` binaries by default, although you can specify your own password-generation app when running `abra <app> secret generate` by providing the `<cmd>` argument.
## Inserting secrets manually
For third-party API tokens, like OAuth client secrets, or keys for services like Mailgun, you will be storing values you already have as the appropriately-named Docker secrets. `abra` provides a convenient interface to the underlying `docker secret create` command:
```
abra app example_wordpress secret insert db_password v2 "your-secret-here"
```
## Rotating a secret
So, given how [secret versions](#versions) work, here's how you change a secret:
1. Find out the current version number of the secret, e.g. by running `abra app example_wordpress config`, and choose a new one. Let's assume it's currently `v1`, so by convention the new secret will be `v2`.
2. Generate or insert the new secret:
```
abra app example_wordpress secret generate db_password v2
```
or
```
abra app example_wordpress secret insert db_password v2 "foobar"
```
3. Edit the app configuration to change which secret version the app will use:
```
abra app example_wordpress config
```
4. Re-reploy the app with the new secret version:
```
abra app example_wordpress deploy
```
## Storing secrets in `pass`
The Co-op Cloud authors use the [UNIX `pass` tool][pass] to share sensitive data, including Co-op Cloud secrets, and `abra <app> secret...` commands include a `--pass` option to automatically manage generated / inserted secrets:
```
# Store generated secrets in `pass`:
abra app new wordpress --secrets --pass
abra app example_wordpress secret generate --all --pass
# Store inserted secret in `pass`:
abra app example_wordpress secret insert db_password v2 --pass
# Remove secrets from Docker, and `pass`:
abra app example_wordpress secret rm --all --pass
```
This functionality currently relies on our specific `pass` structure; patches to make that configurable are very welcome!
## What makes secrets secure?
TODO
[docker secrets]: https://docs.docker.com/engine/swarm/secrets/
[immutable]: https://en.wikipedia.org/wiki/Immutable_object
[pass]: https://www.passwordstore.org

24
docs/server-side.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Running abra on the server
---
## Why?
If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local computer.
To install `abra` on a different server than you'll be hosting your apps, just follow [getting started guide](/overview/) as normal.
If you want to install `abra` on the same server, there's one change.
Instead of providing your SSH connection details when you run `abra server add ...`, just use `default`:
```
abra server add default
```
!!! note "Technical details"
This will tell `abra` to look at the Docker system running on the server, instead of a remote one.
Make sure to back up your `~/abra/` directory on the server, or put it in version control, as well as other files you'd like to.

33
docs/strategy.md Normal file
View File

@ -0,0 +1,33 @@
---
title: Project strategy
---
## What are the goals of the Co-op Cloud?
!!! note "Yes, we do have a blog"
Some leading thoughts are outlined in the [project launch blog post](https://autonomic.zone/blog/co-op-cloud/) also.
From our experiences working and organising as Autonomic, the tech co-op who initiated Co-op Cloud, we know that the progressive tech movement lack reliable and cost-effective technical means for providing an alternative to “Big Tech” cloud services.
The urgency for providing an alternative comes out of the understanding that the concentration of our digital lives within the private sphere of corporate providers (e.g. [GAFAM](https://degooglisons-internet.org/en/)) represents a loss of freedom due to the threat to our privacy and self-determination through surveillance and monopolisation.
As a movement, we cannot compete with corporate providers in terms of cost and scale. Their network effects and available capital means that no one project, product or organisation can create the required shift to a more widespread public interest technology.
Our strategy is to mutualise our resources to create this shift. Co-op Cloud is an attempt to create a new shared resource - an open and democratically managed, open standards based, copyleft licensed, libre software infrastructure project.
## Compensation for contributions
We think that it is important to focus on making the libre software ecosystem sustainable. This has historically [not been the case](https://www.fordfoundation.org/media/2976/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure.pdf).
It feels important to contextualise this position. In the words of [LURK](https://lurk.org):
> Big tech and an abusive misunderstanding of free and open source software practices have led us to believe that software production, server maintenance and on-line services should be free as in gratis. However there is no such things as a free lunch and software does not exist in a vacuum. If we want sustainable alternatives and a diverse cultural sector, these alternatives and the humans behind them, need to be supported.
And a short excerpt from [Seven Theses On The Fediverse and The Becoming Of FLOSS](https://archive.transmediale.de/content/seven-theses-on-the-fediverse-and-the-becoming-of-floss):
> Without substantial funding for ongoing development and maintenance, these projects will remain contingent upon the exploitation of the free labor of well-meaning individuals, or subject to the whims of people making time for their FLOSS hobby.
We want to build a flourishing, inclusive, accessible project and paying people for their work (not just writing source code, but other forms of organising and care work too!) has a role to play in that. We think that making it possible to compensate contributors for working on Co-op Cloud is a way to get involved with self-organising sustainability from the start.
We haven't worked this all out. We've opened up an [Open Collective account](https://opencollective/coop-cloud) and we're running this as an "invite only mode" approach. **If you want to make a contribution to Co-op Cloud and you'd like to be compensated, please [come and chat to us first](https://docs.coopcloud.tech/contact/).**

35
docs/styles/extra.css
View File

@ -3,38 +3,3 @@
--md-primary-fg-color--light: #202674; --md-primary-fg-color--light: #202674;
--md-primary-fg-color--dark: #ee4a33; --md-primary-fg-color--dark: #ee4a33;
} }
/* Navbar styling tweaks */
.md-search__form {
background-color: rgba(0, 0, 255, 0.20);
}
.md-tabs {
background-color: #6A9CFF;
}
.md-tabs__item {
font-weight: 600;
}
/* Footer styling tweaks */
.md-footer {
background-color: #485FC7;
}
.md-footer-meta {
background-color: rgba(0, 0, 0, 0.45);
}
/* Mobile sidebar styling tweaks */
.md-nav__source {
background-color: #A7C5FF !important;
}
.md-nav--primary .md-nav__title {
background-color: #6A9CFF !important;
color: var(--md-primary-bg-color) !important;
}

35
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Troubleshooting
---
## SSH / connection problems
Assuming:
- Hostname: `coopcloud.example.com`
- User: `username`
- Port: `222`
### Step 1: Can you SSH to the server normally?
Does `ssh username@coopcloud.example.com -p2222` work?
If not, run through your standard oh-no-why-doesn't-SSH-work troubleshooting 🍀.
### Step 2: Can you run remote Docker commands over SSH?
Does `ssh username@coopcloud.example.com -p2222 docker ps` work?
If not:
- Is the remote Docker daemon running?
- Is your user in the `docker` group?
### Step 3: Does your Docker context work?
```
[user@hostname ~]$ DOCKER_CONTEXT=coopcloud.example.com docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
If you get an error message instead:
- Use `abra server ls` / `docker context ls` to double-check the SSH connection details
- Try removing the context with `docker context rm coopcloud.example.com`, then re-add it

90
mkdocs.yml
View File

@ -1,25 +1,20 @@
--- ---
site_author: Co-op Cloud site_author: Co-op Cloud
site_name: "Co-op Cloud: Public Interest Infrastructure" site_name: Co-op Cloud
site_url: https://docs.coopcloud.tech site_url: https://coopcloud.tech
theme: theme:
name: material name: material
features: features:
- navigation.expand
- navigation.instant - navigation.instant
- navigation.sections - toc.integrate
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
palette: palette:
primary: light pink primary: light pink
accent: purple accent: purple
logo: img/favicon.ico logo: img/favicon.ico
favicon: img/favicon.ico favicon: img/favicon.ico
custom_dir: custom_theme/
copyright: Copyleft 🄯 2022 Co-op Cloud copyright: Copyleft 🄯 2021 Co-op Cloud
markdown_extensions: markdown_extensions:
- meta - meta
@ -38,60 +33,37 @@ markdown_extensions:
emoji_generator: !!python/name:materialx.emoji.to_svg emoji_generator: !!python/name:materialx.emoji.to_svg
nav: nav:
- "Introduction": - "Introduction": index.md
- index.md - Getting started guide:
- "Frequently asked questions": intro/faq.md - Architecture overview: overview.md
- "Project strategy": intro/strategy.md - Deploy your first app: deploy.md
- "Project status": intro/bikemap.md - App catalogue: apps.md
- "Managed hosting": intro/managed.md - App config guide: app-config-guide.md
- "Get in touch": intro/contact.md - Recipe maintainer guide: recipe-maintainer-guide.md
- "Credits": intro/credits.md - Abra guide: abra.md
- "Operators Guide": - Frequently asked questions: faq.md
- operators/index.md - Contributing guide: contribute.md
- "New operators tutorial": operators/tutorial.md - Community organising: comm-org.md
- "Operations handbook": operators/handbook.md - Admin guide:
- "Maintainers Guide": - How to manage the .abra directory: config.md
- maintainers/index.md - Manage secret data: secrets.md
- "New maintainers tutorial": maintainers/tutorial.md - Understanding networking: networking.md
- "Packaging handbook": maintainers/handbook.md - Back-up and restore an app: backup-restore.md
- "Organisers Guide": - Scale an app up to handle more traffic: scale.md
- organisers/index.md - Roll an app back to a previous version: rollback.md
- "Organising handbook": organisers/handbook.md - Running abra on the server: server-side.md
- "Recipes": - Under the hood:
- recipes/index.md - Recipe structure: recipe-structure.md
- "Abra": - Strategy: strategy.md
- abra/index.md - Bike map: bikemap.md
- "Install": abra/install.md - Troubleshooting: troubleshooting.md
- "Quick start": abra/quickstart.md - Managed Hosting: managed.md
- "Upgrade": abra/upgrade.md - Get in touch: contact.md
- "Hack": abra/hack.md - Acknowledgements: credits.md
- "Troubleshoot": abra/trouble.md
- "Cheat Sheet": abra/cheat-sheet.md
- "Get Involved":
- get-involved/index.md
- "Democracy":
- democracy/index.md
- "Decisions": democracy/decisions.md
- "Glossary":
- glossary/index.md
plugins: plugins:
- search - search
- awesome-pages - awesome-pages
- translations:
default_language: en
languages:
en: english
pl: polski
extra:
alternate:
- name: English
link: /en/
lang: en
- name: Polish
link: /pl/
lang: pl
repo_name: coop-cloud/docs.coopcloud.tech repo_name: coop-cloud/docs.coopcloud.tech
repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech

7
renovate.json
View File

@ -1,7 +0,0 @@
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"packageRules": [{
"matchUpdateTypes": ["minor", "patch"],
"automerge": true
}]
}

9
requirements.txt
View File

@ -1,5 +1,4 @@
mkdocs-awesome-pages-plugin==2.8.0 mkdocs-awesome-pages-plugin==2.5.0
mkdocs-material-extensions==1.1.1 mkdocs-material-extensions==1.0.3
mkdocs-material==9.0.12 mkdocs-material==7.2.6
mkdocs==1.4.2 mkdocs==1.2.2
mkdocs-translations>=0.1.1