File Storage

File field components allow interaction with a file storage provider. Since <form.io> does not itself store files, a provider needs to be configured.

Custom Url

Custom Url Provider does not have any settings in the Project Settings. Instead, it is set in the Url field on the form component when it is added to a form.

In order to use a Custom Url Provider, you will need to set up a service that can upload and serve files. See https://github.com/danialfarid/ng-file-upload#server for setting up a compatible service.

The information posted to the server will be

{
  file: file
}

The server should save the contents of the file somewhere and return the following object.

{
  url: 'http://link.to/file',
  name: 'The_Name_Of_The_File.doc',
  size: 1000
}

You may return additional attributes if desired.

S3

The S3 Storage provider allows file storage and retrieval using any S3 compatible service but was specifically designed for Amazon Web Services S3.

For an on premise compatible solution, try minio. See our minio installation guide.

If you haven’t already done so, go to Amazon Web Services and sign up for an account.

In order to use S3, you will need to configure an IAM user and an S3 bucket.

Create an IAM user

  • Go to Services ❘ IAM and click on the Users tab.

  • Click the Add User button.

  • Enter a user name such as “S3” and then click Programatic Access, then click Next button.

  • Skip the page where you add the user to a group.
  • On the last page, press Create User
  • On the next page, it should show you your access keys. You will need to copy those and add them to a note on your computer which you will need later.

  • Now press Close button, which will take you back to the users list.
  • Find the user we just created and then click on their name, which will show you their Summary
  • Copy the ARN of that user and save it along with your Access Keys from earlier.

  • We are now ready to create the S3 bucket.

Create an S3 bucket

  • Go to Services ❘ S3
  • Click + Create Bucket and enter a name and region for the bucket and click Next

  • Click Next for all the other pages of the wizard to complete the creation of the bucket. We can configure all of these options after the bucket is created.
  • Next click on that bucket which will take you to the bucket page. Click on the Permissions tab.

  • Now, click on Bucket Policy button and then add the following policy to your bucket.

     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Sid": "UploadFile",
           "Effect": "Allow",
           "Principal": {
             "AWS": "arn:aws:iam::XXXXXX:user/S3"
           },
           "Action": [
             "s3:GetObject",
             "s3:PutObjectAcl",
             "s3:PutObject"
           ],
           "Resource": "arn:aws:s3:::formio-upload/*"
         }
       ]
     }
    
  • If you wish to have Public Read access to your files, then you will need to add the following rule to your policy.

     {
        "Sid": "crossdomainAccess",
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::formio-upload/crossdomain.xml"
     }
    

    So that it looks like the following.

     {
        "Version": "2012-10-17",
        "Statement": [
           {
              "Sid": "UploadFile",
              "Effect": "Allow",
              "Principal": {
                 "AWS": "arn:aws:iam::XXXXXX:user/S3"
              },
              "Action": [
                 "s3:GetObject",
                 "s3:PutObjectAcl",
                 "s3:PutObject"
              ],
              "Resource": "arn:aws:s3:::formio-upload/*"
           },
           {
              "Sid": "crossdomainAccess",
              "Effect": "Allow",
              "Principal": "*",
              "Action": "s3:GetObject",
              "Resource": "arn:aws:s3:::formio-upload/crossdomain.xml"
           }
        ]
     }
    
  • Important Note You will need to make sure you replace the arn:aws:iam::XXXXXX:user/S3 with the ARN you copied when you created the user, and also replace the formio-upload with the name of your new bucket.
  • Next click on CORS configuration and add the following.

     <?xml version="1.0" encoding="UTF-8"?>
     <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <CORSRule>
            <AllowedOrigin>*</AllowedOrigin>
            <AllowedMethod>POST</AllowedMethod>
            <AllowedMethod>PUT</AllowedMethod>
            <AllowedMethod>GET</AllowedMethod>
            <AllowedMethod>HEAD</AllowedMethod>
            <MaxAgeSeconds>3000</MaxAgeSeconds>
            <AllowedHeader>*</AllowedHeader>
        </CORSRule>
     </CORSConfiguration>
    
  • You may replace <AllowedOrigin>*</AllowedOrigin> with the domain names of the sites your app will be running on or leave it open.
  • Make sure you save the configuration and the bucket settings.

S3 Bucket Encryption (optional)

Form.io also supports S3 Encryption to provide further safety with the files that are stored within the S3 system. If you wish to enable this feature, you can do so by click on the Properties tab, then click on Default Encryption and then provide the encryption you would like to use.

Your S3 bucket should now be properly configured.

Enter S3 Project Settings

  • On form.io go to your Project Settings page and Click on Integrations ❘ File Storage ❘ S3 Storage
  • Enter the information for the IAM user and S3 bucket you just created. Make sure to provide all the necessary configurations that match the setup that you configured. For example, like this.
  • The following credentials can be provided.

    Setting Description Example
    Use Minio Server Check this if you would like to use these settings to Connect to a Minio Server  
    Access Key ID This is the IAM user Access Key ID that you copied when setting up the S3 user. ALIAQIQUCRXQ7Q2I8UYQ
    Secret Access Key This is the IAM user Secret Access Key that you copied when setting up the S3 user. IykVuiJPYidDhTWyFSfyIOVXuX7tIwIpCC3Sqql/
    Bucket Name The name of the bucket you created. formio-upload
    Bucket URL If you are using your own S3 compatible server, then provide the url here. https://formio-upload.s3.amazonaws.com/
    Bucket Region The region which you setup your Bucket within us-west-2
    Starts With This is the top-most folder you wish to place all the files from this project within. files/
    Access Control List Determines the Access Control of the files within this bucket. private
    S3 Encryption The type of encryption you are using for this S3 bucket. AES-256
    KMS Key ID Only valid if you are using KMS encryption where you then need to provide your KMS Key ID  
    Max Size The maximum file size for uploads going into this bucket. 100MB
    Policy Expiration The amount of seconds that the Upload policy is valid for 360
  • Now make sure to Save the project settings.
  • Now for every File component that you add to a form, you will need to select the S3 Storage dropdown as follows.

Dropbox

The Dropbox storage provider allows using the Dropbox service for storing files within your project.

To connect your project to Dropbox, go to Project Settings->File Storage->Dropbox. Click the Connect to Dropbox button. A window will open asking you to authorize Form.io to access your Dropbox account. After allowing it you should see “Your project is connected to a Dropbox account.” This indicates that your project has successfully connected.

Next add a File component to a form and select “Dropbox” as the storage provider. Save the form.

All files added to that file component should now be immediately added to the Dropbox folder. Files are limited to 150MB.

Minio

The Form.io platform supports On-Premise or Private Cloud file hosting through the use of the Minio Server. These instructions will talk you through how to setup and configure your Minio deployment to point to the Form.io platform.

Minio Setup

To deploy a new Minio server, you will need to first install Docker either on your local machine or on your privte cloud server. Once you have Docker installed, you can then run the following command to spin up a new Minio instance.

docker run -itd \
  -e "MINIO_ACCESS_KEY=CHANGEME" \
  -e "MINIO_SECRET_KEY=CHANGEME" \
  --name formio-minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -v ~/minio/data:/data \
  -v ~/minio/config:/root/.minio \
  minio/minio server /data

In this example, it is important to note that I have Minio mounting a local computer folder @ ~/minio. This can be changed to any internal drive on your machine where you would like to store the Minio files.

Once minio is running, you can then verify that by typing the following.

docker ps

You should see something that looks like the following.

You can also go to the URL http://localhost:9000 in your browser and see the minio interface. You can log in using the MINIO_ACCESS_KEY and MINIO_SECRET_KEY that you used to spin up the minio server.

Once, there you will want to creata a new Bucket by clicking on the + icon toward the bottom right of the screen, and then select Create Bucket. You can give your bucket any name you wish and then press Enter to save.

Keep the name of the bucket for future configurations.

Using NGROK for local testing

If you wish to test this capability locally, it is recommended to use the tool NGROK to create a web accessible proxy to your local host. Once you have NGROK installed, you can then run the following on your machine to create a secure web tunnel to your localhost.

ngrok http 9000

With this running, you should then be able to go to the HTTPS url provided in your browser where you will see your locally running Minio server portal. Keep this URL for the next steps.

Form.io Configuration

Now that you have a Minio Server running, the next thing you will need to do is configure your Form.io portal settings to point to the running Minio server. You can do this by logging into https://portal.form.io and navigate to your Project. Once there you will then go through the following steps.

  • Go to **Settings ❘ Integrations ❘ File Storage ❘ Amazon S3 / Minio (On-Premise, Private Cloud) **
  • Click on the checkbox that says Use Minio Server
  • Next, configure the Minio settings as follows where you will provide your own configurations.

Press Save to save your settings.

Create a Form that uses Minio

Next, you will need to create a new Webform that has a File component. In the configurations of the file upload, you will want to make sure that you have selected S3 as the Storage provider.

You are now off and running with the Minio!