Configuration

Before you can begin using Flask S3Viewer, you should set up authentication credentials. Credentials for your AWS account can be found in the IAM Console. You can create or use an existing user. Go to manage access keys and generate a new set of keys.

Configure credentials

Install AWS CLI.

pip install awscli

If you have the AWS CLI installed, then you can use it to configure your credentials file:

aws configure

Alternatively, you can create the credential file yourself. By default, its location is at ~/.aws/credentials. and Flask S3Viewer is going to use the credential file.

Minimum settings

This is a minimal setup for using flask s3viewer. First install the dependency packages.

pip install flask flask_s3_viewer

Import flask and flask_s3_viewer

from flask import Flask

from flask_s3_viewer import FlaskS3Viewer
from flask_s3_viewer.aws.ref import Region

Initiailize Flask application and FlaskS3Viewer.

# Init Flask
app = Flask(__name__)

# Init Flask S3Viewer
s3viewer = FlaskS3Viewer(
    # Flask App
    app,
    # Namespace must be unique
    namespace='flask-s3-viewer',
    # Hostname, e.g. Cloudfront endpoint
    object_hostname='http://flask-s3-viewer.com',
    # Put your AWS's profile name and Bucket name
    config={
        'profile_name': 'PROFILE_NAME',
        'bucket_name': 'S3_BUCKET_NAME'
    }
)

# Register Flask S3Viewer's router
s3viewer.register()

if __name__ == '__main__':
    app.run(debug=True, port=3000)

The values in the code above are mandatory. If the setting is finished, run your Flask application and visit http://localhost/{namespace}/files, e.g. http://localhost:3000/flask-s3-viewer/files.

You can get example codes over here.

---

User Guides

It is about various advanced settings.

Multiple bucket settings

You can also initiailize multiple bucket.

...

s3viewer = FlaskS3Viewer(
    ...
)

# Init another bucket
s3viewer.add_new_one(
    namespace='another_namespace',
    object_hostname='http://anotherbucket.com',
    config={
        'profile_name': 'PROFILE_NAME',
        'bucket_name': 'S3_BUCKET_NAME'
    }
)
s3viewer.register()

Mount a specific path in a bucket for browsing

You can mount a specific path in the bucket to the browser. ( Be careful not to end the path with / )

...

s3viewer = FlaskS3Viewer(
    ...
)

# Init another bucket
s3viewer.add_new_one(
    namespace='another_namespace',
    object_hostname='http://anotherbucket.com',
    config={
        'profile_name': 'PROFILE_NAME',
        'bucket_name': 'S3_BUCKET_NAME'
        'base_path': 'path/to/your/folder'
    }
)
s3viewer.register()

Limit the file extensions

You can limit the file extensions that are uploaded, if you want.

s3viewer = FlaskS3Viewer(
    ...

    # allowed extension
    allowed_extensions={'jpg', 'jpeg'},
    config={
        ...
    }
)

Choose the design template

Flask S3 Viewer supports the templates below.

Template namespace	Design type	Description
base	Default	Not designed at all
mdl	Material Design Lite	link

s3viewer = FlaskS3Viewer(
    ...
    # Enter template namespace (default: base)
    template_namespace='mdl',
    config={
        ...
    }
)
s3viewer.register()

Controll large files

If you want to controll large files (maybe larger than 5MB ~ maximum 5TB), I recommand to set like below. Flask S3Viewer is going to use S3’s presigned URL. It’s nice to controll large files.

s3viewer = FlaskS3Viewer(
    ...
    # Change upload type to 'presign'
    upload_type='presign',
    config={
        ...
    }
)
s3viewer.register()

but you must do S3’s CORS settings before like set above.

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "POST",
            "PUT",
            "GET",
            "HEAD",
            "DELETE"
        ],
        "AllowedOrigins": [
            "http://localhost:3000"
        ],
    }
]

Use Caching

S3 is charged per call. Therefore, Flask S3Viewer supports caching (currently only supports file caching, in-memory database will be supported later).

s3viewer = FlaskS3Viewer(
    ...
    config={
        ...
        # Flask S3Viewer will cache the list of s3 objects, if you set True
        'use_cache': True,
        # Where cached files will be written
        'cache_dir': '/tmp/flask_s3_viewer',
        # Time To Live
        'ttl': 86400
    }
)
s3viewer.register()

Full example

...

 s3viewer = FlaskS3Viewer(
     # Flask app
     app,
     # Namespace must be unique
     namespace='flask-s3-viewer',
     # Enter template namespace(default: base)
     template_namespace='mdl',
     # File's hostname
     object_hostname='http://flask-s3-viewer.com',
     # Allowed extension
     allowed_extensions={},
     # Bucket configs and else
     config={
         # Required
         'profile_name': 'PROFILE_NAME',
         # Required
         'bucket_name': 'S3_BUCKET_NAME',
         'region_name': Region.SEOUL.value,
         # Not necessary, if you configure aws settings, e.g. ~/.aws
         'access_key': 'AWS_IAM_ACCESS_KEY',
         'secret_key': 'AWS_IAM_SECRET_KEY',
         # For S3 compatible
         'endpoint_url': None,
         # Flask S3Viewer will cache the list of s3 objects, if you set True
         'use_cache': True,
         # Where cached files will be written
         'cache_dir': '/tmp/flask_s3_viewer',
         # Time To Live
         'ttl': 86400,
     }
 )

Things to know

Searching

• Search only working in EN, because of JMESPath.