heilaaks/snippy repository overview

⁠Snippy

Snippy is a software development and maintenance notes manager. It allows organizing and sharing examples and solutions from self hosted or shared storage through command line interface or via REST API server. Snippy may be able to help you when working with different open source components that all have different commands, settings and issues.

⁠Features

Main features include:

• Linux command line tool or a REST API server⁠.
• Manage notes in three categories.
• Supports Markdown, YAML, JSON and text formats.
• Organize notes with metadata like groups and links.

⁠Installation

To install as a tool, run:

pip install snippy --user

To install as a server, run:

docker pull docker.io/heilaaks/snippy

⁠Usage

⁠Starting the server without specifying UID and GID

When the server is run without defining UID or GID with --user option, the value from Dockerfile USER instruction is used. The USER in the Docker image can be considered random even though it is fixed. Do not rely to the UID defined in Dockerfile to allocate volume from the host. This means that this use case does not support persistent volume mount from host.

docker run \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

⁠Starting the server with UID or GID defined from host

In this use case the UID defined by host will override the value set in the USER instruction in the Dockerfile. This allows defining a volume from host with the help of deterministic UID.

# Example 1: Run container services with UID 1000.
docker run \
    --user 1000 \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

It is also possible to defined the GID with UID when starting the server container.

# Example 2: Run container services with UID 1000 and GID 1001.
docker run \
    --user 1000:1001 \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

In order be able to maintain the updated content in Snippy container, a persistent volume must be mounted from the host. The directory path in the host must be absolute path for the docker run command.

The example below will create new folder under user's home directory. The container is started with the same user (UID) than user starting the containers. This makes it possible to access a volume from the container. If different UID would be used in the container to run the Snippy server, it would not be able to access the volume from the host.

Because this creates a volume outside the Docker container, there are no default content in storage unless explicitly told. Because of this, there is the --defaults flag. This tells the server to import the default content when the server is started. If you do not want to use the default content, leave the --defaults option from the example.

# Example 3: Persistent volume is reserved from host.
mkdir -p /home/$(whoami)/.local/share/snippy
docker run \
    --user $(id -u) \
    --volume /home/$(whoami)/.local/share/snippy:/volume \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --defaults --debug

⁠Starting the service with UID allocated by 'user namespaces' feature

In this use case the UID in container does not map to UID in host. This use case assumes that the docker user namespaces feature is activated in host that runs the containers [4].

This is the use case suited for multi-tenant environments and running multiple containers.

In this case the UID is not explicitly set from host. It is assumed that in this case the container is started with UID 0 (root).

docker run \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

⁠Running container with a readonly filesystem

It is possible to run the server with readonly filesystem if the container is started with --tmpfs /tmp. The server must have a temporary folder to write a server own heartbeat [8].

The --tmpfs option does not allow any configuration like size of the tmpfs or file permissions. The option also does not work with the Docker swarm. If there is a use case where the --tmpfs cannot be used, the same can be done with the --mount option which allows limits in size, file permissions and works with Docker swarm. The --tmpfs is used here because it is easier to configure.

# Example 1: Run with the same UID as the user who starts the container.
docker run \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --read-only \
    --tmpfs /tmp \
    --detach \
    heilaaks/snippy --server-readonly

# Example 2: Run with UID defined from host.
docker run \
    --user 1000 \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --read-only \
    --tmpfs /tmp \
    --detach \
    heilaaks/snippy --server-readonly

⁠Change the IP and port visible in host that runs the container

The --publish command line option defines what is the IP and port that is visible in host. The example below shows how the exposed port and IP address in the host can be changed to 173.23.22.212:80.

The /tcp in the publish option means that only TCP port in running container is mapped to 173.23.22.212:80. Because Snippy is a HTTP server, only TCP protocol is needed.

docker run \
    --publish=173.23.22.212:80:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

⁠Change REST API server base path

It is possible to change the Snippy REST API server base path. The server API base path must always start and end with a slash.

docker run \
    --env SNIPPY_SERVER_BASE_PATH_REST=/api/ \
    --publish=127.0.0.1:8080:32768/tcp \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

⁠Use host network

This is not recommended configuration because it is not secure and breaks the container native design "assume nothing from host".

It is possible to bind the server IP directly from the host that runs the Snippy Docker continer. This configuration is prone to port conflicts since some other service in host may already use required port.

This example is the only valid reason to modify the Snippy server host and port in the container.

docker run \
    --env SNIPPY_SERVER_HOST=127.0.0.1:8080 \
    --net=host \
    --name snippy \
    --detach \
    heilaaks/snippy --debug

⁠Use Docker container as a command line tool

It is possible search content with the help of Docker container like with the CLI version of the tool.

The procedure is different depending on the Snippy server storage:

Snippy server running local (Sqlite) storage inside container

This example uses only the immutable container. This means that only the content imported by default into the Docker image can be searched.

In this use case the container is alive only during the command. Use the --rm option to remove the exited container after the command has been run.

There is no need to add a name for the the container. The name is just an extra parameter that is not needed and which may clash with existing names and fail the Docker command.

The Docker container will write JSON logs by default. The example below disables this so that the last 'OK' or 'NOK: *' is printed as normal text instead of JSON log.

# Example 1: Connect to a volume mount used by Snippy server.
docker run \
    --rm \
    --env SNIPPY_LOG_JSON=0 \
    heilaaks/snippy search --sall docker

Snippy server running local (Sqlite) storage mounted from host

If there is a Snippy server running and the container has mounted a volume from host, it is possible to access another server data by directly reading it's volume from the host. The --user and --volume must be defined correctly so that the container is able to read the volume allocated for the sever.

# Example 1: Connect to a volume mount used by Snippy server.
docker run \
    --rm \
    --user $(id -u) \
    --volume /home/$(whoami)/.local/share/snippy:/volume \
    --env SNIPPY_LOG_JSON=0 \
    heilaaks/snippy search --sall docker