github.com/cozy/cozy-stack@v0.0.0-20240327093429-939e4a21320e/docs/instance.md (about)

     1  [Table of contents](README.md#table-of-contents)
     2  
     3  # Instances
     4  
     5  A single cozy-stack can manage several instances. Requests to different
     6  instances are identified through the `Host` HTTP Header, any reverse proxy
     7  placed in front of the cozy-stack should forward this header.
     8  
     9  ## Creation
    10  
    11  An instance is created on the command line:
    12  
    13  ```sh
    14  $ cozy-stack instances add <domain> [flags]
    15  ```
    16  
    17  The flags are documented in the
    18  [`instances add manpage`](cli/cozy-stack_instances_add.md).
    19  
    20  It registers the instance in a global couchdb database `global/instances`
    21  and creates the proper databases ($PREFIX/$DOCTYPE) for these doctypes:
    22  
    23  -   `io.cozy.apps`
    24  -   `io.cozy.contacts`
    25  -   `io.cozy.files`
    26  -   `io.cozy.jobs`
    27  -   `io.cozy.konnectors`
    28  -   `io.cozy.notifications`
    29  -   `io.cozy.oauth.clients`
    30  -   `io.cozy.permissions`
    31  -   `io.cozy.sessions.logins`
    32  -   `io.cozy.settings`
    33  -   `io.cozy.shared`
    34  -   `io.cozy.sharings`
    35  -   `io.cozy.triggers`
    36  
    37  Then, it creates some indexes for these doctypes, and some directories:
    38  
    39  -   `/`, with the id `io.cozy.files.root-dir`
    40  -   the trash, with the id `io.cozy.files.trash-dir`
    41  -   `/Administrative`
    42  -   `/Photos`
    43  -   `/Photos/Uploaded from Cozy Photos`
    44  -   `/Photos/Backed up from my mobile`
    45  
    46  **The names are localized:** If a locale is provided through the CLI, the
    47  directories will be created with names in this locale.
    48  
    49  Then it creates the basic settings with the options from the CLI.
    50  
    51  Finally, applications from the `--apps` CLI option are installed.
    52  
    53  ## Onboarding
    54  
    55  At the end of the instance creation, the CLI returns a token, called
    56  `registerToken`. The `registerToken` can be used to send a link to the user,
    57  where they will be able to choose their password. After that, the instance
    58  is said to be onboarded, and the user can use it normally.
    59  
    60  ## Listing
    61  
    62  To get the list of all the instances that can be served by this server :
    63  
    64  ```sh
    65  $ cozy-stack instances ls [flags]
    66  ```
    67  Flags are optional, [more info on ls](cli/cozy-stack_instances_ls.md).
    68  
    69  ## Destroying
    70  
    71  An instance is destroyed through the command line. A confirmation is asked from
    72  the CLI user unless the --force flag is passed:
    73  
    74  ```sh
    75  $ cozy-stack instances destroy <domain>
    76  ```
    77  
    78  When the deletion of an instance starts, the stack puts a flag `deleting` on
    79  the instance. This flag avoids that someone can try again to destroy the
    80  instance while the stack is doing cleaning before the real deletion (like
    81  deleting accounts). It's possible to remove manually the flag via the command
    82  `cozy-stack instance modify --deleting=false <domain>` to force a deletion that
    83  has failed.
    84  
    85  ## Blocking
    86  
    87  If you manage several instances on your stack, you can block some instances.
    88  When an instance is blocked (for whatever reason), the user cannot use his Cozy
    89  anymore and has to wait to be unblocked.
    90  
    91  ```sh
    92  $ cozy-stack instances modify <domain> --blocked
    93  ```
    94  
    95  A `--blocking-reason` can be added for specific cases and to inform a user the
    96  reason of the blocking.
    97  
    98  Several pre-included reasons are included, but you can define your owns if needed. These reasons are:
    99  
   100  - `"LOGIN_FAILED"`: The instance was blocked because of too many login attempts
   101  - `"PAYMENT_FAILED"`: The instance waits for a payment to be done
   102  - `"UNKNOWN"`: The instance was blocked for an unknown reason
   103  
   104  ## Modifying
   105  
   106  If you want to edit an instance, see [`instances modify manpage`](cli/cozy-stack_instances_modify.md).