DEV Community: Alex

Deploy Appwrite functions using GitHub actions

Alex — Mon, 25 Mar 2024 00:09:01 +0000

I'm embarking on an exciting journey to integrate automation into my homelab setup. My plan? Leverage GitHub Actions to
streamline tasks within my Kubernetes cluster. It's been a while since I've dived into GitHub Actions, so I figured,
why not blend this endeavor with my passion for Appwrite? This approach not only eases me back into the workflow but
also sets the stage for some reusable code that I can reference to in future projects.

You might be wondering, "Why go through the hassle of using GitHub actions instead of simply linking my GitHub account to the Appwrite Console?" The answer lies in the seamless integration GitHub actions offer within a larger CI/CD pipeline. Imagine having Functions that depend on the presence of a new collection in the database. With GitHub actions, I can orchestrate this in a single swoop, eliminating the need for multiple systems to awkwardly pass the baton to each other.

Prerequisites

A GitHub Account (and some basic git knowledge)
A Cloud or Self-hosted Appwrite instance
NodeJS installed (I use the latest LTS, NodeJS 20, but your milage may vary)

Appwrite

Begin by navigating to the Appwrite cloud or your own self-hosted installation console. Then, initiate a new project (or if you already have a project, proceed to the subsequent step).

Next, proceed to create an API key. This essential step authorizes the GitHub runner to interface with Appwrite. Ensure you save this key somewhere accessible for future reference throughout this tutorial.

Navigate to the project's homepage and find the "+" sign adjacent to the API Key section under the "Integrate with your server" area. Use the guided setup process, and click on the eye icon to reveal your API key, which will appear as a lengthy string of characters.

Appwrite CLI

Let's start with the assumption that your Appwrite instance is a blank slate with no existing resources, and you haven't installed the CLI yet. If you're ahead of the game and already have the CLI set up, there's a neat feature that allows you to synchronize appwrite.json with your current setup. For guidance on this, you can refer to the CLI Documentation.

npm install -g appwrite-cli

Once the above command has finished, go ahead and follow the steps below. This logs your local machine into the Appwrite console, initialises your project and creates a test function.

# Login to appwrite instance
appwrite login
? Enter your email [CONSOLE_EMAIL]
? Enter your password [CONSOLE_PASSWORD]

# Initialise Project
appwrite init project
? How would you like to start? Link this directory to an existing Appwrite project
? Choose your Appwrite project.
> github-actions-test ([PROJECT_ID])

# Create a Function
appwrite init function
? What would you like to name your function? My Awesome Function
? What ID would you like to have for your function? unique()
? What runtime would you like to use?
  Node.js (node-16.0)
> Node.js (node-18.0)
  PHP (php-8.0)
  Ruby (ruby-3.0)
  Python (python-3.9)
  Dart (dart-2.17)
  Dart (dart-3.1)

Save contents of the codeblock below in ./github/workflows/deploy-functions.yaml

name: Deploy Appwrite Functions
on: workflow_dispatch
jobs:
  deploy-functions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm install -g appwrite-cli
      - run: appwrite -v
      - run: appwrite client --endpoint ${{ vars.APPWRITE_URL }} --projectId ${{ vars.APPWRITE_PROJECT_ID }} --key ${{ secrets.APPWRITE_API_KEY }}
      - run: appwrite deploy function --all --yes

Once this is all done and dusted, commit and push this to your repository. Moving on we will go and set your repository up to work with actions and execute!

GitHub Setup

Navigate to the repository where you've just uploaded your code and workflow. From there, proceed to Settings > Secrets and Variables > Actions, and make sure you're viewing the 'Secrets' tab.

Select 'New Repository Secret'. When prompted for the secret's name, label it APPWRITE_API_KEY and input the lengthy string I advised you to keep safe into the secret value field. Don't forget to save your changes.

Then, switch to the variables tab. You'll follow a similar procedure as before, but this time create two new variables named APPWRITE_PROJECT_ID and APPWRITE_URL. You can locate your project ID and URL within your project's settings. Below is an example to guide you.

Navigate to the Actions tab within your repository. On the left side, you'll find 'Deploy Appwrite Functions'. Click on it, then select the 'Run workflow' dropdown and proceed by submitting it with the default settings.

Cross your fingers, do a little dance, and hit refresh! With a bit of patience (and maybe some magic), you should witness your workflow springing to life. Allow it a few minutes—perhaps enough time to brew a cup of tea or engage in a quick interpretive dance. Then, mosey on back to the Appwrite console. Lo and behold, your function should be standing there, deployed and ready for action. You've now officially become a GitHub Actions wizard. Take a bow, and accept your virtual round of applause. Congratulations!

Resources

Creating a forum with React and Appwrite – Part 3

Alex — Sat, 23 Apr 2022 00:18:58 +0000

Welcome to the second part in this multi-part series on creating a Forum with React and Appwrite. If you havn't seen it already, go and checkout part 2 here.

In this installment we're aiming to be able to add new posts and comment on them. It's going to be a meaty one, so grab your cup of tea and snacks!

Database

As with any new part of this series, we need to get a few things ironed out in the database.

Firstly head over to your Appwrite Console and click 'Database'. We're going to need a new collection to hold our comments for the articles. Click add collection and fill out the prompt like below:

Attributes

Head over to the attributes tab for the collection you just created and add the following attributes:

Attribute ID	Type	Size	Required
postId	String	255	Yes
userId	String	255	Yes
content	String	255	No
author	String	255	No

Indexes

Head over to the Indexes tab for the collection you just created and add the following Indexes:

Index Key	Type	Attributes
userId	key	userId (ASC)
postId	key	categoryId (ASC)

Collection Permissions

One thing I've forgotten to mention throughout the series is you'll need to setup your collection permissions. By default it's set to collection wide. We dont want this.

Later on in the series we may need to adjust some permissions to allow things to be edited by an Administrator. But for now, go through each of your collection settings and double check they're set to the following:

Profiles, Posts and Comments collections:

Categories collection:

🛠️ On The Tools

With the pleasantries out the way, let's get cracking! Head over to your .env file and add the following to the bottom of the file:

REACT_APP_COMMENTS_COLLECTION=6263216f884ae458a235

Make sure you replace 6263216f884ae458a235 with the comments collection id found in your appwrite console.

Create Documents

We need to add some code into src/Services/api.js to provide an interface for our UI to be able to create new doucmnets into our database. Add the following somewhere into the file:

createDocument: (collectionId, data, read, write) => {
    return api.provider().database.createDocument(collectionId, 'unique()', data, read, write);
},

Essentially what we're doing here is telling AppWrite's SDK to call the REST endpoint that handles document creation with a unique ID along with the permission and data information for the document.

New Post

Open src/Components/Forum/Posts/NewPostButton/NewPostButton.js and update it to look like the following:

const style = {
    position: 'absolute',
    top: '50%',
    left: '50%',
    transform: 'translate(-50%, -50%)',
    width: 400,
    bgcolor: 'background.paper',
    boxShadow: 24,
    p: 4,
};

export function NewPostButton(props) {
    const {REACT_APP_POSTS_COLLECTION} = process.env;

    const user = useSelector((state) => state.user);

    const [isLoggedIn, setIsLoggedIn] = useState(user.isLoggedIn);
    const [open, setOpen] = React.useState(false);

    const [title, setTitle] = React.useState('');
    const [content, setContent] = React.useState('');

    const handleOpen = () => setOpen(true);
    const handleClose = () => setOpen(false);

    useEffect(() => {
        setIsLoggedIn(user.isLoggedIn);
    });

    function submitPost(){
        let {fetchPosts, id} = props;

        api.createDocument(REACT_APP_POSTS_COLLECTION, {
            'categoryId': id,
            'userId': user.account.$id,
            'title': title,
            'content': content,
            'author': user.account.name,
        }, ['role:all']).then(() => {
            setTitle('');
            setContent('');

            handleClose();
            fetchPosts();
        })
    }

    return isLoggedIn ? (
        <>
            <Button style={{marginTop: '1rem'}} variant="contained" color="primary" onClick={handleOpen} disableElevation>New Post</Button>

            <Modal
                open={open}
                onClose={handleClose}
                aria-labelledby="modal-modal-title"
                aria-describedby="modal-modal-description"
            >
                <Box sx={style}>
                    <Typography id="modal-modal-title" variant="h6" component="h2">
                        New Post
                    </Typography>
                    <TextField
                        fullWidth
                        label="Tile"
                        id="title"
                        sx={{mt: 1}}
                        value={title}
                        onChange={(e) => {setTitle(e.target.value)}}
                    />
                    <TextField
                        sx={{mt: 1}}
                        id="content"
                        label="Content"
                        fullWidth
                        multiline
                        rows={4}
                        onChange={(e) => {setContent(e.target.value)}}
                    />
                    <Button sx={{mt: 1}} variant="contained" onClick={() => submitPost()}>Submit</Button>
                </Box>
            </Modal>
        </>
    ) : null;
}

Your also going to need to update src/Components/Forum/Posts/Posts.js to pass through the category id through the props to the child component:

return (
    <>
        <Grid container>
            <Grid item xs={6}>
                <NewPostButton id={searchParams.get("id")} fetchPosts={fetchPosts}/>
            </Grid>
            <Grid item xs={6} style={{textAlign: 'right'}}>
                <BackButton/>
            </Grid>
        </Grid>
        {posts.map((post) => (
            <PostItem title={post.title} description={post.description} author={post.author} key={post.$id} id={post.$id} />
        ))}
    </>
);

Add Comment

We're going to need a new button to click to create a new comment.
It's very similar to the new post button. We could refactor it to leverage it for both scenarios; but I'm lazy. We will revisit this but for now, create a new file src/Components/Post/Components/NewCommentButton/NewCommentButton.js with the following:

export function NewCommentButton(props) {
    const user = useSelector((state) => state.user);

    const [isLoggedIn, setIsLoggedIn] = useState(user.isLoggedIn);

    useEffect(() => {
        setIsLoggedIn(user.isLoggedIn);
    });

    return isLoggedIn ? <Button style={{marginTop: '1rem'}} variant="contained" color="primary" disableElevation>New
        Comment</Button> : null;
}

View Post & Comments

Lets render the post and comments! Create a new file src/Components/Post/Post.js with the following content:

export function Post(props) {
    const {REACT_APP_COMMENTS_COLLECTION, REACT_APP_POSTS_COLLECTION} = process.env;

    let [comments, setComments] = useState([]);
    let [post, setPost] = useState({});
    const [searchParams, setSearchParams] = useSearchParams();
    const navigate = useNavigate();

    function fetchComments() {
        api.listDocuments(REACT_APP_COMMENTS_COLLECTION, [Query.equal('postId', searchParams.get("id"))]).then((result) => {
            setComments(result.documents);
        });
    }

    function fetchPost(){
        api.getDocument(REACT_APP_POSTS_COLLECTION, searchParams.get("id")).then((post) => {
            setPost(post)
        });
    }

    useEffect(() => {
        if (searchParams.get("id")) {
            fetchComments();
            fetchPost();
        } else {
            navigate('/');
        }
    }, []);

    return (
        <>
            <Grid container>
                <Grid item xs={6}>
                    <NewCommentButton id={searchParams.get("id")} fetchComments={fetchComments}/>
                </Grid>
                <Grid item xs={6} style={{textAlign: 'right'}}>
                    <BackButton/>
                </Grid>
            </Grid>

            <Card style={{marginTop: '1rem'}}>
                <CardContent>
                    <Typography gutterBottom variant="h5" component="div">
                        {post?.title}
                    </Typography>
                    <Typography variant="body2" color="text.secondary">
                        {post?.content}
                    </Typography>
                    <Typography variant="body2" color="text.secondary">
                        by {post?.author}
                    </Typography>
                </CardContent>
            </Card>

            {comments.map((comment) => (
                <Card style={{marginTop: '1rem'}}>
                    <CardContent>
                        <Typography variant="body2" color="text.secondary">
                            {comment?.content}
                        </Typography>
                        <Typography variant="body2" color="text.secondary">
                            by {comment?.author}
                        </Typography>
                    </CardContent>
                </Card>
            ))}
        </>
    );
}

Final Adjustments

Now we've got the leg work out the way, let's make some adjustments so what you've developed is useable. Head over to your App.js file to add a new route. Under your 'posts' route, add the following:

<Route path="/post" element={<Post />}/>

Finally, let's make posts clickable! Open src/Components/Forum/Posts/PostItem/PostItem.js and update <CardActionArea> to:

<CardActionArea onClick={() => {
    navigate(`/post?id=${id}`);
}}>

You may also need to add this in the same function (under export function PostItem(props) {):

const navigate = useNavigate();

You should now be able to add new posts, for example:

Also, if you login as another user you can see other comments and posts:

Conclusion

By now you should have a fairly basic, but working message board. You can now list categories and topics aswell as view comments. From now on the articles will be much more 'byte sized'; Focussing on adding smaller features rather than larger pieces of work.

As always, hit me up on twitter or comment here if I've missed something or you need something clarifying.

Whats next?

We're going to carry on adding features in future articles. I'm also doing a 'Sub series' that takes the finished project and converts it into AWS' Amplify instead of Appwrite with Lambda functions, API Gateway and Icognito! Chuck us a follow on Twitter or on Dev.to if you want to be the first to know.

What features do you want to see added? Drop a comment or get in touch with suggestions!

📚 Learn more

Lambda Series

Alex — Fri, 22 Apr 2022 22:06:26 +0000

Currently writing notes along side writing my Appwrite React forum series to replace the appwrite element write Lambda. Aiming to release these as soon as the current series is done. Goal is to be able to clone the finished appwrite series and then replace the api interfaces with the AWS SDK.

Idea is to cover cognito, lambda and api gateway (with route 53, ofcourse). Bare with, middle of trying to organise this mess :-)

ps. part 3 should be out over the next few days - drop a follow to get notified!

Creating a forum with React and Appwrite – Part 2

Alex — Mon, 28 Mar 2022 22:11:02 +0000

Welcome to the second part in this multi-part series on creating a Forum with React and Appwrite. If you havn't seen it already, go and checkout part 1 here. Already read it? Great. Let's get cracking!

This part maybe a short one - I want to have post addition in its own article due to starting to use appwrite functions. Please bare with!

Database

Firstly head over to your Appwrite Console and click 'Database'. We're going to need a new collection to hold our posts for the categories. Click add collection and fill out the prompt like below:

Attributes

Head over to the attributes tab for the collection you just created and add the following attributes:

Attribute ID	Type	Size	Required
categoryId	String	255	Yes
userId	String	255	Yes
title	String	255	No
content	String	255	No
author	String	255	No

Indexes

Head over to the Indexes tab for the collection you just created and add the following Indexes:

Index Key	Type	Attributes
userId	key	userId (ASC)
categoryId	key	categoryId (ASC)

💾 New Files

Making sure you're in the project folder, you'll want to run the following command to fetch a few new template files I've created for you:

git pull

You'll see the following new files added:

These files relate to listing posts in the categories aswell as two new UI elements to handle going back to the category list and creating new posts (next installment!).

🖱 Click categories

First we need to add the functionality to be able to navigate 'into' each category when it is clicked. Navigate to src/Components/Forum/Categories/Category/Category.js and update it to look like the following:

export function Category(props){
    const {id, name, description} = props;

    const navigate = useNavigate();

    return (
        <Card style={{marginTop: '1rem'}}>
            <CardActionArea onClick={() => {
                // Navigate to the 'posts' route with the 'id' property of the category ID.
                navigate(`/posts?id=${id}`);
            }} >
                <CardContent>
                    <Typography gutterBottom variant="h5" component="div">
                        {name}
                    </Typography>
                    <Typography variant="body2" color="text.secondary">
                        {description}
                    </Typography>
                </CardContent>
            </CardActionArea>
        </Card>
    )
}

You'll also need to go into src/Components/Forum/Categories/Categories.js and update the following:

return categories.map((category) => (
        <Category key={category.$id} id={category.$id} name={category.name} description={category.description} />
));

Provided you've done everything correct (Including downloading the new provided files described previously) you should now be able to click into categories:

✉️ List Posts

Looking at 'fake' posts isn't very fun - nor is it useful. I've gone ahead and already added some test posts in the database so we know we're querying them.

Head over to src/Components/Forum/Posts/Posts.js and add the following before the return statement:

const [searchParams, setSearchParams] = useSearchParams();
const navigate = useNavigate();

function fetchPosts(){
    api.listDocuments(REACT_APP_POSTS_COLLECTION, [Query.equal('categoryId', searchParams.get("id"))]).then((result) => {
        setPosts(result.documents);
    }))
}

useEffect(() => {
    if(searchParams.get("id")){
        fetchPosts();
    } else {
        navigate('/');
    }
}, []);

Then in the return statement, replace <PostItem title={'Test PostItem'} /> with:

{posts.map((post) => (
    <PostItem title={post.title} description={post.description} author={post.author} key={post.$id}/>
))}

You should now be able to see the posts that you added in the Appwrite console when you click on the corrosponding cateogory:

Conclusion

In this part we've gone through how to click on categories and list posts. In the nest part we will be actually adding new posts straight from the forum UI aswell as ensuring our permissions are set correctly (And the ground work for Admin roles to edit / remove posts!).

As ever, if I've not described something well or missed something, reach out! Keep an eye on my Twitter for when I post the next article!

📚 Learn more

Creating a forum with React and Appwrite – Part 1

Alex — Sun, 27 Mar 2022 21:01:04 +0000

In this multi-part series, we will be creating a fully functional forum that will cover many of Appwrite’s features. Stay tuned as we hope to evolve the forum as the series goes on to cover as many Appwrite Topics as possible.

Prerequisites

During this guide we're going to make a few assumptions. The main one being that you've got access to an Appwrite installation (either locally or remotely). If you've not got one, check out this installation guide. Additionally we will be assuming:

You've got the Appwrite CLI installed (see here)
Understand simple programming concepts

You can find the (evolving) project over at: https://github.com/Swinkid/appwrite-forum

Let's get setup!

Enough chit-chat. Now we know what we're doing, lets get setup! First, we’ll need to clone the project that includes important files that take the leg work out of starting the project from scratch.

git clone https://github.com/Swinkid/appwrite-forum-setup
cd appwrite-forum-setup/
npm install

Next, we'll need to create the project on our Appwrite installation. Instead of doing it manually, I've populated the appwrite.json files with collections. This will ensure our Collection and Project IDs are the same (Important for the .env file!)

alex@Alex-PC:~/IdeaProjects/appwrite-forum-setup$ appwrite init project
? How would you like to start? (Use arrow keys)
❯ Create a new Appwrite project
  Link this directory to an existing Appwrite project

We need an .env file to tell react where our Appwrite resources are. I've put an example in the project, so simply do the following:

cp .env.example .env

If you then go ahead and open this .env file, you'll see the following:

REACT_APP_ENDPOINT=http://localhost:3000/v1
REACT_APP_PROJECT=624096a0130c10e3dceb
REACT_APP_ADMIN_TEAM=6240989c8d1a6db01d39
REACT_APP_CATEGORY_COLLECTION=6240986d4947526ebfd4

Since we generated the project and collections, you shouldn't need to adjust this. Later on in the project we will be adding to this file.

Finally, we're going to actually need to populate our forum categories. Headover to the categories collection in appwrite and follow the ~~white rabbit, neo~~ gif.

🛠️ Let's get coding!

Since the main focus is how we interface with Appwrite, some of the pages have been pre-populated for you. Your welcome to modify these how you'd like. You will be implementing the 'business' logic for each of the pages.

Login

Go ahead and open up src/Components/Auth/Login/Login.js. You'll find a function named handleSubmit that contains the following code:

const handleSubmit = (event) => {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    console.log({
        email: data.get('email'),
        password: data.get('password'),
    });
};

At the moment all the code is doing it outputting the cotents of the email and password forms to the browsers console. Let's fix that, replace console.log(...); with the following:

api.login(data.get('email'), data.get('password')).then((result) => {
    // Store logged in 'state' in redux.
    dispatch(login({
        account: result.account,
    }))
    navigate('/');
}).catch((error) => {
    setErrors(true);
});

Simply, all we're doing is storing the account data in Redux and then redirecting the user back to the forum's home page. Time to give it a wirl!

Register

Next, we're going to figure out the register page. Go and open src/Components/Auth/Register/Register.js. Just like the login page, you'll have a handleSubmit function. As before, replace the console.log(...); statement with the following:

api.createAccount(data.get('email'), data.get('password'), data.get('firstName') + ' ' + data.get('lastName')).then((result) => {
    navigate('/login');
}).catch((error) => {
    setErrors(true);
})

You should now be able to register your own account without heading to the Appwrite console! :D

Conclusion

Phew! That was alot! Today we've started creating a forum where users can login, register and view the forum's categories. In the next installment, we're going to be adding to this and allow new posts to be created. Keep an eye on my Twitter for when I post the next article!