.. _user/services/structure/resources/file:

*************
Cybus::File
*************

Docker containers and volumes can contain any sort of files. With the
Cybus::File resources, additional files can be written into a given :ref:`volume
<user/services/structure/resources/volume>` with the content specified in the
commissioning file.

.. note:: |feature_not_on_kubernetes|

The life-time of such a file is similar to that of a *volume*: Upon enabling the
service, the file will be newly created by the Connectware and the specified
content will be written into the file, potentially overwriting any other content
that might have been existing at this file path beforehand. Subsequently, the
file will neither be deleted nor truncated by the Connectware, neither on
disabling the service nor on any other occasion. The file will be deleted
together with the volume, once the volume gets deleted manually.


Properties
===========

============== ============ ============= ==========
Property       Type         Required      Default
============== ============ ============= ==========
`volume`_      ``string``   Required
`filepath`_    ``string``   Required
`content`_     ``string``   Required
`writeMode`_   ``enum``     Optional      ``create``
============== ============ ============= ==========

volume
------

The reference to the docker volume to which this file should be written.

- type: ``string``

filepath
---------

The absolute path and filename of the file to be written inside the volume.

- type: ``string``

content
-------

The content of the file as a base64 encoded string.

- type: ``string``

writeMode
----------

Choosing the writing mode when writing the file. `Create` - Create the file with
given content if not existing, but if existing, check whether it has the given
content, and if it has a different content, throw an error (i.e. don’t overwrite
any different content). `Overwrite` - Create the file with the given content,
either creating it newly or overwriting a previously existing file. `Append` -
Append the given content to the file. If it already exists, the given content is
appended. If it does not exist, the file is newly created with the given
content.

- type: ``enum`` which must be one of these values: ``create``, ``overwrite,
  ``append``.
- default: ``create``


Example
=======

.. code-block:: yaml
  :linenos:

  myVolume:
    type: Cybus::Volume

  myFile:
    type: Cybus::File
    properties:
      volume: !ref myVolume
      filepath: '/data/myFile.txt'
      content: 'Zm9vYmFyCg=='
      writeMode: create