fake-gcs-server

fake-gcs-server provides an emulator for Google Cloud Storage API. It can be
used as a library in Go projects and/or as a standalone binary/Docker image.

The library is available inside the package
github.com/fsouza/fake-gcs-server/fakestorage
and can be used from within test suites in Go package. The emulator is
available as a binary that can be built manually, downloaded from the releases
page or pulled from Docker
Hub (docker pull fsouza/fake-gcs-server).

Using the emulator in Docker

You can stub/mock Google Cloud Storage as a standalone server (like the datastore/pubsub emulators)
which is ideal for integration tests and/or tests in other languages you may want to run the
fake-gcs-server inside a Docker container:

docker run -d --name fake-gcs-server -p 4443:4443 fsouza/fake-gcs-server

Preload data

In case you want to preload some data in fake-gcs-server just mount a
folder in the container at /data:

docker run -d --name fake-gcs-server -p 4443:4443 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server

Where the content of ${PWD}/examples/data is something like:

.
└── sample-bucket
    └── some_file.txt

To make sure everything works as expected you can execute these commands:

curl --insecure https://0.0.0.0:4443/storage/v1/b
{"kind":"storage#buckets","items":[{"kind":"storage#bucket","id":"sample-bucket","name":"sample-bucket"}],"prefixes":null}

curl --insecure https://0.0.0.0:4443/storage/v1/b/sample-bucket/o
{"kind":"storage#objects","items":[{"kind":"storage#object","name":"some_file.txt","id":"sample-bucket/some_file.txt","bucket":"sample-bucket","size":"33"}],"prefixes":[]}

This will result in one bucket called sample-bucket containing one object called some_file.txt.

Running with HTTP

fake-gcs-server defaults to HTTPS, but it can also be used with HTTP. The flag
-scheme can be used to specify the protocol.
The binding port will be -port (defaults to 4443).
For example, the previous example could be changed to pass -scheme http:

docker run -d --name fake-gcs-server -p 4443:4443 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server -scheme http

And now we can curl it without the --insecure flag and using http://
instead of https://:

curl http://0.0.0.0:4443/storage/v1/b
{"kind":"storage#buckets","items":[{"kind":"storage#bucket","id":"sample-bucket","name":"sample-bucket"}],"prefixes":null}

curl http://0.0.0.0:4443/storage/v1/b/sample-bucket/o
{"kind":"storage#objects","items":[{"kind":"storage#object","name":"some_file.txt","id":"sample-bucket/some_file.txt","bucket":"sample-bucket","size":"33"}],"prefixes":[]}

Running with both HTTPS and HTTP

To start both HTTPS and HTTP servers, pass -scheme both.
HTTPS will bind to -port (defaults to 4443) and HTTP will bind to -port-http (defaults to 8000).
For example, the previous example could be changed to pass -scheme both:

docker run -d --name fake-gcs-server -p 4443:4443 -p 8000:8000 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server -scheme both

Using with signed URLs

It is possible to use fake-gcs-server with signed URLs, although with a few caveats:

• No validation is made on the query params (signature, expiration ...)
• You need your client to modify the URL before passing it around (replace
  storage.googleapis.com with something that points to fake-gcs-server)
• You need to configure fake-gcs-server to accept this local URL (by setting
  -public-host)

Available server flags

fake-gcs-server supports various features that can be configured through flags
upon start. Use the -help flag to list all of them alongside their usage
instructions

docker run --rm fsouza/fake-gcs-server -help

Client library examples

For examples using SDK from multiple languages, check out the
examples directory.

Building the image locally

You may use docker build to build the image locally instead of pulling it
from Docker Hub:

docker build -t fsouza/fake-gcs-server .